CI Production Preview Nuxt 4 Cloudflare Workers TypeScript pnpm

A Nuxt 4 + NuxtHub starter on a full Cloudflare stack (D1 SQLite · KV · R2 · Workers) with GitHub Actions deploys and a Claude Code agent setup baked in. PR → Cloudflare Workers preview. Merge to main → production ships. D1 migrations apply during each build.

Deep version (conventions, layer ownership, hard rules): CLAUDE.md. CLI reference: packages/cli/README.md.

This is a generic template. Two slash commands adapt it to your actual product — no manual file editing required:

/onboard # business interview → rewrites brand strings, colors, .env, user-facing labels
/go-live # walks you through Cloudflare + GitHub credentials → provisions all resources + wires CI

Run /onboard first if you're starting fresh (the brand still says "Nuxt Template"). Then /go-live once you're ready to ship. Both commands are re-runnable.

pnpm install
pnpm cli dev setup # creates .env from .env.example + generates auth secrets
pnpm cli dev up # nuxt :3002 + maildev (smtp :1025, web :1080)

Open http://localhost:3002/auth/login and click Sign in as Admin Agent or Sign in as User Agent — the /api/auth/demo/login route auto-creates the user with the right ability preset. No seeding step required for the demo flow.

pnpm cli dev setup is idempotent: rerun it any time; it updates the three auth secrets in place rather than appending duplicates.

NuxtHub emulates D1, KV, and R2 locally under .data/ — no containers, no connection strings. pnpm dev (alias for pnpm cli dev up) applies pending D1 migrations on boot.

These commands POST to dev-only routes (only mounted in development mode) and require the dev server to be running:

pnpm cli dev seed # POST /api/auth/demo/dev-seed (creates seed users)
pnpm cli dev provision --email you@example.com # create a user + session
pnpm cli dev login --email you@example.com # issue a session for an existing user
pnpm cli dev cleanup --emails you@example.com # delete users + sessions

pnpm cli db generate # migration from schema diff
pnpm cli db migrate # apply to local .data/
pnpm cli db migrate --remote # apply to remote D1
pnpm cli db sql "SELECT count(*) FROM users"
pnpm cli db reset # wipe .data, re-migrate

pnpm cli verify # lint → typecheck → test; mirrors CI exactly
pnpm cli verify --json # per-step pass/fail

pnpm cli dev setup writes the three required auth secrets. The rest live in .env.example — copy what you need into .env and fill in the values.

Check what you have at any time:

pnpm cli doctor # human-readable table of every env/tool check
pnpm cli doctor --json # machine-readable; exit 1 if any check fails

You need a GitHub account and a Cloudflare account.

Create a token at https://dash.cloudflare.com/profile/api-tokens with Workers Scripts + D1 + Workers KV + R2 edit (and workers_observability edit if you keep logging on). Grab the account id from Workers & Pages → account id.

Add both to your shell (or .env):

export CLOUDFLARE_API_TOKEN=...
export CLOUDFLARE_ACCOUNT_ID=...

gh auth login # only needed once

pnpm cli deploy setup --env all --dry-run # preview the plan, mutate nothing
pnpm cli deploy setup --env all # do it

That single command:

1. Verifies your Cloudflare token and GitHub auth.
2. Resolves-or-creates the D1 database, KV namespaces, and R2 bucket (prod + preview).
3. Writes the resulting IDs to GitHub Actions variables (consumed at build).
4. Sets CLOUDFLARE_API_TOKEN and PREVIEW_NUXT_AUTH_SECRET as GitHub secrets.
5. Bulk-pushes every NUXT_* / CRON_SECRET from your .env to the production Worker as runtime secrets.

Want to manage Worker secrets via the Cloudflare dashboard instead? Pass --skip-worker-secrets.

Push a branch, open a PR → the Preview workflow runs:

• Builds with NITRO_PRESET=cloudflare-module and CLOUDFLARE_ENV=preview (D1 migrations apply during the build).
• Deploys to Cloudflare Workers (wrangler deploy --env preview).
• Posts a sticky PR comment with the preview URL.

Merging to main → the Production workflow builds (migrating D1) and runs wrangler deploy.

pnpm cli deploy status # latest CI runs + Worker deployments
pnpm cli deploy logs # tail the production Worker (streams until Ctrl-C)

The selfhost layer (layers/selfhost/) lets your users deploy this app into their own Cloudflare account directly from the product's Settings → Self-hosting page — no CLI or DevOps knowledge required.

How it works:

1. The user pastes a Cloudflare API token with Workers + D1 + KV + R2 edit permissions.
2. The app verifies the token, probes write capabilities, and idempotently creates the required Cloudflare resources (D1, KV namespace, R2 bucket).
3. It fetches the latest bundle.json from this repo's GitHub releases, verifies the SHA-256 checksum, applies D1 migrations, and uploads the Worker.
4. On subsequent deploys the stored token (AES-GCM encrypted at rest) is reused — one click to update.

Publishing a release bundle:

git tag v1.2.3 && git push --tags # triggers .github/workflows/release.yml

The release workflow builds the Cloudflare Worker and runs node scripts/make-deploy-bundle.mjs, which packages the output into a bundle.json asset attached to the GitHub release.

Required env vars for self-hosting to work:

For non-trivial features, run:

/team <feature description>

That spawns parallel fullstack-dev + qa-visual + ux-researcher teammates per the .claude/agents/ setup. See .claude/agents/README.md for the coordination rules and the layer-ownership invariant that keeps parallel work untangled.

For solo work, the project-wide skills (nuxt-ui, vue, pinia, etc.) under .claude/skills/ load automatically when relevant.

Full conventions — TDD rules, component naming, layer structure, the auth ability model, the deploy-pipeline tradeoffs — are in CLAUDE.md.

Stack-level scripts: