next-scaffold
Skill1 starsChanged 39 days agoMITView on GitHub
Scaffolds a new Next.js App Router app from scratch (no next.config.ts yet) — OpenNext on Cloudflare, tokenless /api pass-through to the API, TanStack Query, shadcn/ui; dashboard and saas variants. Triggers: 'scaffold next', 'create next app', 'next saas template'.
In this repository23 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- harness-auditSkill
- skill-benchSkill
- ask-biginSkill
- bigin-harness-setupSkill
- contract-syncSkill
- debug-workflowSkill
- discovery-workflowSkill
- epic-workflowSkill
- flutter-figma-handoffSkill
- go-scaffoldSkill
- knowledge-distillSkill
- model-routerSkill
- napkinSkill
- nodejs-scaffoldSkill
- nuxt-marketing-scaffoldSkill
- nuxt-scaffoldSkill
- nuxt-ui-figma-handoffSkill
- project-scaffoldSkill
- session-handoffSkill
- sprint-distillSkill
- task-workflowSkill
- write-testsSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 37
Add a page, component, store, or route handler to an existing Next app → task-workflow
- Very specific: line 40
Add governance files to an already-scaffolded repo → bigin-harness-setup
- Distinctive: line 46
Check the target directory:
- Very specific: line 63
No theme/base-color question — as of this writing the shadcn CLI's init command has no non-interactive base-color flag (only …
- Distinctive: line 69
Write the answers to a JSON file outside the target repo (temp/scratchpad dir):
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
next-scaffold
This skill is mechanical: gather config, write it, run the script, relay its output. Do not deliberate — no thinking needed on any step here.
Scaffolds a Next.js app (no BFF) from a chosen template. The mechanical work is done by a deterministic script — scripts/scaffold.mjs (Node stdlib only, cross-platform, zero prompts). This skill's only jobs: decide the config values, write them to a JSON file, run the script, report the result. Do not perform any scaffolding steps yourself.
Stack: Next.js 16.3.8 (App Router, TypeScript, pinned exactly) on Cloudflare Workers via @opennextjs/cloudflare, Tailwind CSS v4, shadcn/ui, Zustand, TanStack Query, Zod, Vitest + Testing Library, simple-git-hooks + lint-staged. No BFF: the browser reaches the paired Go API through a tokenless same-origin /api/v<N>/** pass-through (a rewrites() in next.config.ts, server-only build-time API_ORIGIN), and the API owns the HttpOnly cookie session and data persistence.
Templates (template config field, default starter):
| slug | source | shape |
starter (default) | create-next-app (no clone, no block) | minimal Next + shadcn/ui base (Button/Card/Tooltip) + the pass-through preset, no auth wired |
dashboard | create-next-app + shadcn dashboard-01 block | working admin shell straight at /dashboard (sidebar, charts, data table on sample data) |
saas | create-next-app + shadcn input/label primitives + hand-authored pages | public site + private /dashboard — cookie-session auth against the paired go-scaffold API: login/signup/logout call its /api/v1/auth/* endpoints through the pass-through, the API sets the HttpOnly session cookie, and a client AuthGate redirects to /login on a 401 from GET /api/v1/user/profile (see references/artifacts.md) |
Unlike nuxt-scaffold's 9 templates (6 of which clone a whole separate GitHub repo from nuxt-ui-templates), shadcn/ui has no equivalent gallery of full standalone app templates — only an official block registry (dashboard-01, login-03, etc.) of individual compositions added into an existing app via shadcn add. next-scaffold therefore ships exactly the two templates that get real bespoke treatment in the Nuxt world (saas, dashboard) plus the default — not a 1:1 count match. See references/bootstrap.md for the full rationale.
Governance (CLAUDE.md,
.claude/rules/, AI guides,bash-guard.mjs) is not this skill's job — runbigin-harness-setupafterward to overlay it.
Prerequisites: Node.js 20+, pnpm. Scaffolding is in-place into the target directory (for a brand-new project: mkdir my-app first).
When not to use
This skill only ever creates a new project. A request about a Next app that already exists belongs elsewhere — even when it names this exact stack. Zustand, TanStack Query, shadcn/ui, Zod and Vitest are what this scaffold generates; they are not topics it owns.
- Add a page, component, store, or route handler to an existing Next app →
task-workflow - Fix a bug or a failing check →
debug-workflow - Explain how a library in the stack works → answer directly, no skill
- Add governance files to an already-scaffolded repo →
bigin-harness-setup
Step 1: Detect state & confirm
Check the target directory:
next.config.ts(or.js/.mjs) exists + both signature files (vitest.config.ts,.claude/settings.json) +node_modules/all exist → complete scaffold. Say so and stop.next.config.*exists but a signature file ornode_modules/is missing → partial scaffold (prior failed run, or a maintainer'sskipInstall: truerun that still needs installing/verifying). Ask: "Partial scaffold detected — resume (install the preset + apply artifacts + verify)? (yes / no)". If yes → setresume: truein the config and continue to Step 2. If no → stop.- No
next.config.*→ ask: "Scaffold a Next.js app in this repo (non-interactive create-next-app + the /api pass-through preset + OpenNext/Cloudflare config)? (yes / no)". If no → stop.
(The script re-checks all of this and fails fast rather than overwriting — but resolving it conversationally first avoids a wasted run.)
Step 2: Gather config
AskUserQuestion accepts up to 4 questions in a single call, rendered as one widget. Exactly one AskUserQuestion tool call, with a questions array holding both objects below — not two separate calls. They don't depend on each other, so array order doesn't matter.
- Template — options:
Starter — pass-through preset, no auth(recommended/default),Dashboard — shadcn admin shell (dashboard-01 block),SaaS — public site + private dashboard, cookie-session auth. - Dependency freshness — options:
capped — latest minor/patch within the shipped major (safe, default),latest — newest release including a future major(nextitself stays pinned to 16.3.8 under both — OpenNext 1.20.9 is only verified against it).
Then, plain conversational free text (not AskUserQuestion, needs regex validation, so it can't be a 3rd array entry): Project name — kebab-case, default = current directory name, must match ^[a-z0-9]+(-[a-z0-9]+)*$ — re-prompt if it doesn't.
No theme/base-color question — as of this writing the shadcn CLI's init command has no non-interactive base-color flag (only --template/--base/--preset), so next-scaffold accepts whatever its nova default preset picks. Re-verify references/bootstrap.md if the CLI gains one later.
Show a summary as a bullet list (AskUserQuestion's question text doesn't render markdown tables — pipes/dashes show up literally, only **bold** renders), e.g. - **Project name:** my-app, one bullet per field, and confirm. If no → stop.
Step 3: Write config & run the script
Write the answers to a JSON file outside the target repo (temp/scratchpad dir):
{
"projectName": "my-app", // required, kebab-case
"targetDir": ".", // default "."
"packageManager": "pnpm", // BigIn standard; the script rejects anything else
"template": "starter", // "starter" | "dashboard" | "saas"
"versionPolicy": "capped", // "capped" | "latest"
"resume": false, // true only when Step 1 detected a partial scaffold
"gitCommit": true, // final "chore: scaffold Next.js app" commit
"skipInstall": false // advanced/maintainer flag — see below; never set true from Step 2's normal flow
}skipInstall (default false, not part of Step 2's questions) writes every file and merges every package.json entry but never runs create-next-app's install, pnpm add, pnpm simple-git-hooks, shadcn init/add, or the verify stage — the preset packages land in package.json pinned to the latest dist-tag, unresolved, and shadcn/ui is not initialized at all. Use it only for fast maintainer iteration on scaffold.mjs/templates (see references/MAINTAINING.md); the result is not a runnable app until pnpm install + npx shadcn@latest init are run manually. Never set this from the normal user-facing flow.
Then run it from the target directory, streaming output (it can take several minutes — installs + lint + type-check + tests):
node ${CLAUDE_SKILL_DIR}/scripts/scaffold.mjs --config <path-to-config.json>Zero prompts occur once the script starts. Every step it performs (init, version refresh, preset, shadcn/ui, artifacts, hooks, verify, commit) is internal — do not duplicate any of it.
Step 4: Report
- Exit 0 → relay the script's "Next steps" output verbatim.
- Exit 2 → config problem; fix the JSON per the error message and re-run.
- Exit 1 → runtime failure; the last
[scaffold] ERROR:line names the failing stage/command. Common causes: Node < 20, pnpm missing, network failure duringcreate-next-app, or acreate-next-app@16.3.8/shadcn@latestbehavior change (the error will say to re-verifyreferences/bootstrap.md). A failed run partway through leaves a partial scaffold — after fixing the cause, re-run with"resume": true.
Maintainer notes (design rationale, manual validation after changing the script or templates) live in references/MAINTAINING.md. A scaffold run never needs them, so it never reads them.
References
scripts/scaffold.mjs— the scaffold implementation (single file, Node stdlib only).scripts/templates/— source of truth for every file written/merged into the project.references/bootstrap.md— rationale for the command sequence the script executes.references/artifacts.md— rationale + merge semantics for each template.references/modules.md— preset packages, shadcn block registry notes.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

