@timbenniks/contentstack-platform-app-scaffold

[!WARNING] This is an experimental project maintained by Tim Benniks. It is not an official Contentstack project, and there is no official Contentstack support for it beyond reaching out to Tim.

CLI tool to scaffold full-stack Contentstack apps using the Platform SDK. It creates a production-ready Next.js project with shadcn/ui, Tailwind v4, Contentstack design tokens, OAuth-safe proxies, and first-run setup guidance.

What it does

1. Runs create-next-app@latest with TypeScript, Tailwind v4, ESLint, and App Router
2. Initializes shadcn/ui and adds the primitives needed for the selected scaffold
3. Adds @timbenniks/contentstack-platform-sdk as a dependency
4. Overlays Contentstack-specific files based on the features you select:
   • CMA — Server proxy at /api/cma, plus a CMS browser for content types, entries, entry inspection, and assets
   • OAuth — Auth.js v5 integration with createContentstackAuth, setup-aware sign-in/sign-out UI
   • Launch — Server proxy at /api/launch, plus a browser for projects and environments
   • Brand Kit — Server proxy at /api/brandkit, plus a browser for kits and voice profiles
5. Maps the SDK's Venus Design System tokens to shadcn CSS variables via tokens.css
6. Adds a runtime theme toggle with Light, Dark, and Auto using the SDK's theme helpers
7. Adds a scaffold-specific README.md, a root AGENTS.md, and a local Platform SDK skill bundle
8. Adds a typecheck script that generates Next.js route types before running TypeScript

Installation

As a Contentstack CLI plugin

csdx plugins:install @timbenniks/contentstack-platform-app-scaffold

Then run:

csdx scaffold my-app

Standalone with npx

npx @timbenniks/contentstack-platform-app-scaffold scaffold my-app

Global install

npm install -g @timbenniks/contentstack-platform-app-scaffold

Usage

Interactive mode

csdx scaffold my-app

The CLI will prompt you for:

• Framework — Next.js (more coming soon)
• Region — us, eu, au, azure-na, azure-eu, gcp-na, gcp-eu
• Features — CMA, OAuth, Launch, Brand Kit
• OAuth scopes — if OAuth is selected
• Default theme — system, light, or dark
• Package manager — npm, yarn, or pnpm
• Optional env prefills — API keys, organization UIDs, OAuth credentials, and Brand Kit UID

If you select cma, launch, or brandkit, OAuth is added automatically because the scaffold generates browser-facing routes and server proxies. If you opt into env prefills, the scaffold writes a feature-aware .env.local and can auto-generate AUTH_SECRET when left blank.

Non-interactive mode

Pass all options as flags to skip prompts:

csdx scaffold my-app \
  --framework nextjs \
  --region eu \
  --features cma,oauth \
  --scopes "user:read,cm.entries.management:read,cm.assets.management:read" \
  --api-key blt123 \
  --app-id app123 \
  --client-id client123 \
  --client-secret secret123 \
  --auth-secret local-auth-secret \
  --nextauth-url http://localhost:3000 \
  --package-manager pnpm

Flags

| Flag | Description | Default | |------|-------------|---------| | --framework | Framework (nextjs) | prompted | | --region | Contentstack region | prompted | | --features | Comma-separated: cma, oauth, launch, brandkit | prompted | | --scopes | Comma-separated OAuth scopes | prompted if oauth selected | | --package-manager | npm, yarn, or pnpm | prompted | | --api-key | Prefill CONTENTSTACK_API_KEY in .env.local | none | | --organization-uid | Prefill CONTENTSTACK_ORGANIZATION_UID in .env.local | none | | --brand-kit-uid | Prefill CONTENTSTACK_BRAND_KIT_UID in .env.local | none | | --app-id | Prefill CONTENTSTACK_APP_ID in .env.local | none | | --client-id | Prefill CONTENTSTACK_CLIENT_ID in .env.local | none | | --client-secret | Prefill CONTENTSTACK_CLIENT_SECRET in .env.local | none | | --oauth-redirect-uri | Prefill CONTENTSTACK_OAUTH_REDIRECT_URI in .env.local | none | | --auth-secret | Prefill AUTH_SECRET in .env.local | none | | --nextauth-url | Prefill NEXTAUTH_URL in .env.local | none | | --no-git | Skip git initialization | false | | --no-install | Skip dependency installation | false |

Generated project structure

With all features enabled (cma,oauth,launch,brandkit):

my-app/
├── app/
│   ├── api/
│   │   ├── auth/[...nextauth]/route.ts   # OAuth handlers
│   │   ├── cma/[...path]/route.ts        # CMA proxy
│   │   ├── launch/[...path]/route.ts     # Launch proxy
│   │   └── brandkit/[...path]/route.ts   # Brand Kit proxy
│   ├── entries/page.tsx                   # CMS browser landing page
│   ├── entries/[contentTypeUid]/page.tsx  # Paginated entries browser
│   ├── entries/[contentTypeUid]/[entryUid]/page.tsx # Entry inspector
│   ├── assets/page.tsx                    # Asset browser with previews
│   ├── launch/page.tsx                    # Launch projects browser
│   ├── launch/[projectUid]/page.tsx       # Launch project detail
│   ├── brandkit/page.tsx                  # Brand Kits browser
│   ├── brandkit/[brandKitUid]/page.tsx    # Brand Kit detail
│   ├── globals.css                        # shadcn + Venus Design System tokens
│   ├── layout.tsx                         # Root layout with Providers
│   ├── page.tsx                           # Home with sign-in/sign-out
│   ├── theme-toggle.tsx                   # Light / dark / auto switcher
│   └── providers.tsx                      # ContentstackProvider wrapper
├── lib/
│   └── auth.ts                            # createContentstackAuth config
├── types/
│   └── next-auth.d.ts                     # Session type augmentation
├── .env.example                           # Feature-aware env vars
├── AGENTS.md                              # Project-level AI agent guidance
├── README.md                              # Contentstack-specific setup guide
├── skills/contentstack-platform-sdk/      # Local Platform SDK skill bundle
├── next.config.ts                         # SDK transpile config
└── package.json

Environment variables

After scaffolding, copy .env.example to .env.local and fill in your credentials:

cp .env.example .env.local

If you used env-prefill prompts or passed env flags, the scaffold creates .env.local for you. That makes local setup faster and gives CI/integration tests a simple non-interactive path.

The required variables depend on your feature selection:

| Variable | Required when | |----------|--------------| | CONTENTSTACK_REGION | Always | | CONTENTSTACK_API_KEY | CMA | | CONTENTSTACK_ORGANIZATION_UID | Launch or Brand Kit | | CONTENTSTACK_APP_ID | OAuth | | CONTENTSTACK_CLIENT_ID | OAuth | | CONTENTSTACK_CLIENT_SECRET | OAuth | | CONTENTSTACK_OAUTH_REDIRECT_URI | OAuth (optional override) | | AUTH_SECRET | OAuth | | CONTENTSTACK_BRAND_KIT_UID | Brand Kit |

The scaffold always includes the minimum OAuth scopes it needs to function. Extra scopes you select expand the generated proxy permissions. If CONTENTSTACK_OAUTH_REDIRECT_URI is left empty, the SDK auto-detects the callback URL from the request host.

Theme

Generated apps include a built-in Light, Dark, and Auto toggle. It uses @timbenniks/contentstack-platform-sdk/ui/theme, stores the preference in localStorage, and falls back to the scaffold's chosen default when no preference has been saved yet.

CMS Browser

When cma is enabled, the scaffold now generates a richer browser-first CMS UI:

• /entries lists content types and lets you jump straight into a schema
• /entries/[contentTypeUid] gives you a paginated table with content-type switching and inline filtering
• /entries/[contentTypeUid]/[entryUid] exposes tabs for schema fields, system metadata, and raw JSON
• /assets shows asset previews and metadata cards

Requirements

• Node.js >= 18
• npm, yarn, or pnpm

License

MIT