Adobe App Builder TypeScript Base Template

A production-ready starter template for Adobe App Builder projects with full TypeScript support, optimized for Cursor IDE.

🎯 Overview

This repository serves as my foundational template for building Adobe App Builder applications with TypeScript. It provides a robust, type-safe architecture that separates serverless actions (Node.js) from web UI (React), complete with comprehensive Cursor AI rules for intelligent code assistance.

✨ Key Features

🔷 Full TypeScript Support

• Dual TypeScript Configurations: Separate configs for serverless actions (tsconfig.actions.json) and browser-based React UI (tsconfig.web.json)
• Strict Type Checking: Enabled by default with comprehensive type safety
• Modern ES2020+ Syntax: Full support for modern JavaScript/TypeScript features
• Proper Module Interop: Configured for seamless CommonJS/ESM compatibility

🏗️ Production-Ready Architecture

• OpenWhisk Serverless Actions: Node.js 22 runtime with TypeScript compilation via webpack
• React Spectrum UI: Adobe's design system for consistent, accessible user interfaces
• Environment Isolation: Proper boundaries between server-side and client-side code
• Secure Configuration: Environment variables handled according to App Builder best practices

🤖 Cursor AI Optimized

• Comprehensive AI Rules: 500+ lines of workspace rules for intelligent code assistance
• Context-Aware Suggestions: Rules guide AI on App Builder patterns, TypeScript configs, and security best practices
• Project-Specific Guidelines: Auto-enforces proper module boundaries, environment variable handling, and testing patterns

🛠️ Developer Experience

• Pre-configured Webpack: TypeScript compilation with proper config references and source maps
• Organized Test Structure: Tests live in dedicated directories with proper Jest configuration
• Documentation Standards: All docs organized under docs/ with Cursor-specific notes in docs/cursor/
• Storage & Events: Built-in patterns for Adobe State Store, Binary Store, and Custom Events

🚀 Quick Start

Prerequisites

• Node.js 18+ (recommend using nvm)
• Adobe I/O CLI installed globally: npm install -g @adobe/aio-cli
• Adobe Developer Console access with appropriate credentials

Setup

1. Clone this template:

   git clone <your-new-project-url>
   cd <your-new-project>
   npm install

2. Install Gitleaks (Security) 🔒:

   # macOS
   brew install gitleaks
   
   # Linux
   wget https://github.com/gitleaks/gitleaks/releases/download/v8.18.1/gitleaks_8.18.1_linux_x64.tar.gz
   tar -xzf gitleaks_8.18.1_linux_x64.tar.gz
   sudo mv gitleaks /usr/local/bin/
   
   # Windows
   choco install gitleaks

3. Set up pre-commit hook (Automatic):

   # Run the automated setup script
   ./scripts/setup-gitleaks.sh
   
   # Or manually create the hook (see .cursorrules for details)

4. Configure your Adobe I/O credentials:

   aio login

5. Set up environment variables: Setup your project in the Adobe Developer console then download the workspace config locally

   aio app use ~/brand2agency-27200-benge.json -o

6. Run locally:

   # Run both actions and web UI
   aio app run

7. Deploy:

   aio app deploy

🔧 TypeScript Configuration

This template uses a multi-config TypeScript setup optimized for dual runtime environments:

Actions Configuration (tsconfig.actions.json)

• Target: Node.js 22 (CommonJS)
• Modules: Can use fs, path, Adobe I/O libraries
• Cannot Use: Browser APIs, DOM
• Runtime Values: Passed via app.config.yaml inputs (NOT process.env)

Web Configuration (tsconfig.web.json)

• Target: Modern browsers (ESNext)
• Modules: Browser APIs, React, React Spectrum
• Cannot Use: Node.js modules, server-side Adobe libraries
• Environment: Only AIO_* prefixed variables available

Why This Matters

App Builder projects have fundamentally different runtime environments. This setup ensures type safety and prevents runtime errors from importing incompatible modules.

🎨 UI Development with React Spectrum

This template is pre-configured for Adobe's React Spectrum design system:

import { Provider, defaultTheme } from '@adobe/react-spectrum';
import { Button, TextField, Heading } from '@adobe/react-spectrum';

export default function App() {
  return (
    <Provider theme={defaultTheme}>
      <Heading level={1}>My App Builder App</Heading>
      <TextField label="Email" type="email" />
      <Button variant="cta">Submit</Button>
    </Provider>
  );
}

📚 Reference: React Spectrum Documentation

🔐 Security Best Practices

🛡️ Gitleaks Protection

This template includes Gitleaks integration to prevent secrets from being committed:

• Pre-commit hook: Automatically scans staged files before each commit
• Custom rules: Adobe-specific patterns for IMS tokens, API keys, OpenWhisk auth
• CI/CD ready: GitHub Actions workflow included (see .cursorrules)

Quick test:

# Scan entire repository
gitleaks detect --verbose --redact

# Scan staged files only
gitleaks protect --staged

📖 Full documentation:

• See .cursor/rules/gitleaks.mdc for Cursor AI integration guide
• See docs/cursor/SECURITY_SETUP.md for comprehensive security documentation

✅ DO

• Use Gitleaks to scan before every commit (automatic with pre-commit hook)
• Store secrets in Adobe I/O environment configuration
• Pass runtime values to actions via app.config.yaml inputs
• Only use AIO_* prefixed env vars in web UI (exposed via DefinePlugin)
• Keep sensitive credentials out of source control
• Rotate compromised credentials immediately

❌ DON'T

• Read process.env directly in serverless actions
• Hardcode secrets in code or config files
• Import Node.js modules in web UI code
• Commit .env, *.json credential files, or workspace configs
• Use --no-verify to skip pre-commit hooks (except genuine emergencies)
• Store secrets in comments or documentation

🚨 Files That Must Never Be Committed

.env                      # Local environment variables
*.json (credentials)     # Any JSON files with credentials
.wskprops                # OpenWhisk credentials
private.key              # JWT private keys
*.pem, *.p12            # Certificate files

All of these are already in .gitignore ✅

📦 Adobe App Builder Capabilities

This template provides patterns for leveraging key App Builder features:

Capability	Usage
I/O Runtime	Serverless compute for Node.js actions
Custom Events	CloudEvents-compliant event publishing/subscription
State Store	Key-value storage (<64KB per key, 24hr max TTL)
Binary Store	Large file storage with signed URLs
Workspaces	Environment isolation (Dev/Stage/Prod)
Extension Points	dx/excshell/1, dx/asset-compute/worker/1, etc.

🧪 Testing

Tests are organized in the root test/ directory and extension-specific test/ folders:

# Run all tests
npm test

# Run tests in watch mode
npm test -- --watch

# Run tests with coverage
npm test -- --coverage

📖 Documentation Standards

• Project Docs: Place all documentation in docs/
• Cursor Notes: AI-generated summaries go in docs/cursor/
• No Root Markdowns: Keep repository root clean (this README is the exception)

🤝 Using with Cursor IDE

This template includes comprehensive Cursor AI rules that guide code generation, refactoring, and best practices. The AI assistant will:

• ✅ Enforce proper TypeScript patterns for actions vs. web code
• ✅ Prevent importing incompatible modules across boundaries
• ✅ Guide proper environment variable usage
• ✅ Suggest React Spectrum components for UI work
• ✅ Apply Adobe App Builder security best practices
• ✅ Organize tests in the correct directory structure

Tip: The Cursor AI is context-aware of App Builder patterns. Ask it to generate actions, React components, or explain any part of the architecture!

📚 Resources

• Adobe App Builder Documentation
• Adobe I/O Runtime
• React Spectrum
• CloudEvents Specification
• TypeScript Handbook

📝 License

This template is free to use for personal and commercial Adobe App Builder projects.

🙋 About

Created and maintained as a personal base template for rapid Adobe App Builder development with TypeScript. Contributions and suggestions are welcome!

---

Happy Building! 🚀