CLI Scaffold (`create-headlesscore`)

Scaffold a new Next.js frontend project pre-configured for HeadlessCore.

Usage

From monorepo root

npm run create
# or with project name
npm run create my-client-site

After npm publish

npx create-headlesscore my-client-site

With flags

npx create-headlesscore my-site \
  --wordpress-url=http://localhost/headleespro \
  --site-url=http://localhost:3000

What it creates

my-client-site/
├── src/                    # Full nextjs-starter-kit copy
├── public/
├── package.json
├── .env.local              # Auto-generated with secrets
└── ...

The CLI:

1. Copies the Next.js template (from packages/create-headlesscore/template/ or nextjs-starter-kit/)
2. Generates random REVALIDATION_SECRET and PREVIEW_SECRET
3. Writes .env.local with your WordPress and site URLs
4. Runs npm install

Generated .env.local

NEXT_PUBLIC_WORDPRESS_API_URL="http://localhost/headleespro/graphql"
NEXT_PUBLIC_WORDPRESS_URL="http://localhost/headleespro"
NEXT_PUBLIC_SITE_URL="http://localhost:3000"
REVALIDATION_SECRET="<auto-generated>"
PREVIEW_SECRET="<auto-generated>"
WORDPRESS_AUTH_TOKEN=""

Copy the generated secrets into Headless Core → Settings in WordPress admin.

Syncing the template

After modifying nextjs-starter-kit/, bundle it into the CLI package:

npm run sync:template

This runs scripts/sync-template.js which copies nextjs-starter-kit/ → packages/create-headlesscore/template/.

Publishing to npm

# 1. Sync latest template
npm run sync:template

# 2. Publish
cd packages/create-headlesscore
npm publish --access public

Update repository.url in package.json to your GitHub repo before publishing.

Package structure

packages/create-headlesscore/
├── bin/cli.js              # CLI entry point
├── template/               # Synced Next.js starter (generated)
└── package.json

Troubleshooting

Issue	Fix
Template not found	Run from HeadlessCore repo or run npm run sync:template
npm install fails	Ensure Node.js 18+
Secrets mismatch	Copy from generated .env.local to WP admin