scaffold-nextjs

Scaffold a Next.js turborepo with full tooling, GitHub, and Vercel deployment.

• IS: bootstrapping a brand-new Next.js turborepo end to end: app creation, Blode UI, Ultracite tooling, turborepo conversion, GitHub, and Vercel.
• IS NOT: scaffolding a TypeScript CLI or npm package (use scaffold-cli), designing folder structure or module contracts for an existing app (use codebase-architecture), building a page inside an existing app, or choosing visual direction and palettes (use ui-design).

Low-freedom workflow. The reference files are the single source of truth for commands: run them as written, in phase order. Do not reconstruct commands from memory.

Reference Files

Scaffold Workflow

Copy this checklist to track progress:

Scaffold progress:
- [ ] Phase 1: Gather project info
- [ ] Phase 2: Create Next.js app
- [ ] Phase 2.1: Upgrade to TypeScript 7
- [ ] Phase 2.2: Turn on Instant Navigations
- [ ] Phase 3: Install Blode UI components
- [ ] Phase 4: Install Agentation
- [ ] Phase 5: Install Ultracite
- [ ] Phase 6: Convert to Turborepo
- [ ] Phase 7: GitHub and Vercel setup
- [ ] Phase 8: Pre-launch checklist
- [ ] Validation: run the checklist in deploy-and-launch.md

Phase 1: Gather project info

Collect from the user (ask only for what is missing):

Phase 2: Create Next.js app

Run the create-next-app command from references/app-setup.md exactly as written (it pins linter, React Compiler, and package-manager flags). Confirm the app loads at http://localhost:3000 before continuing.

Phase 2.1: Upgrade to TypeScript 7

TypeScript 7 section of references/app-setup.md: install typescript@^7 and confirm npm run build type-checks through tsc. No config accompanies it.

Phase 2.2: Turn on Instant Navigations

Instant Navigations section of references/app-setup.md: set cacheComponents, partialPrefetching, and experimental.turbopackRustReactCompiler in next.config.ts. Cheap here and expensive later, so do it before any route exists. Read the authoring rules in that section before Phase 3; they govern how every page is written.

Phase 3: Install Blode UI components

Blode UI section of references/app-setup.md: shadcn init, register the @blode namespace, then add components.

Phase 4: Install Agentation

Agentation section of references/app-setup.md: install the package, patch app/layout.tsx with the dev-only <Agentation /> guard. Optionally add Google Analytics via @next/third-parties.

Phase 5: Install Ultracite

Ultracite section of references/app-setup.md: delete the Biome placeholder config, run ultracite init with the exact flags listed, then verify with npx ultracite fix and npx ultracite check.

Phase 6: Convert to Turborepo

Move the app into apps/web/ (commands at the end of references/app-setup.md), then from references/turbo-configs.md:

1. Generate root package.json, turbo.json, knip.json, and .gitignore from the templates.
2. Update apps/web/package.json scripts to the turbo-compatible block.
3. Verify apps/web/next.config.ts still has reactCompiler: true, cacheComponents: true, and partialPrefetching: true.
4. Run npm install from the root.
5. Verify npm run dev works from the root (turbo runs apps/web).

Phase 7: GitHub and Vercel setup

From references/deploy-and-launch.md: create the GitHub repo with gh, deploy to Vercel, attach {{domain}}.

Phase 8: Pre-launch checklist

Favicon and OG image steps in references/deploy-and-launch.md, then run the validation checklist at the end of that file. Done only when every validation item passes; “the site loads” is not sufficient evidence.

Placeholder Reference

Templates use {{variable}} syntax. Before Phase 7, sweep for missed placeholders:

grep -rn '{{' --include='*.json' --include='*.ts' --include='*.tsx' --include='*.md' .

A {{name}} left in package.json fails npm install (invalid-name error); a {{domain}} left in metadata ships broken OG URLs.

Gotchas

• No src/ directory. The scaffold uses --no-src-dir; adding src/ later breaks the @/* alias and every shadcn component path.
• Never set experimental.useTypeScriptCli. Since 16.3 the CLI checker is the default, and the flag exists only to switch it back off with false; setting it to true is noise that reads like a requirement.
• Expect raw tsc diagnostics from the CLI checker: no Next.js code frames, and the full tsconfig.json project is checked (tests and .next/dev/types included), so a type error in a file next build used to skip now blocks the build.
• A green next build does not mean navigation is instant. Instant navigation insights are development-only and never fail the build, so validate in next dev and read the overlay.
• Never add output: "standalone". It is for self-hosting, and on Vercel it stops .next/next-server.js.nft.json being written, so the build compiles every page and then dies in Vercel’s onBuildComplete.
• Never set runtime = "edge"; it is deprecated in 16. For work that must outlive the response (analytics, logging), use after() from next/server rather than a floating promise, which Node can cut off the moment the response goes out.
• Add no Turbopack cache config. Disk caching and memory eviction are on by default in 16.3.
• No ESLint or Prettier. Ultracite owns lint and format via Oxlint + Oxfmt; a stray .eslintrc makes the editor disagree with the lefthook pre-commit hook.
• Never run oxlint or oxfmt ad hoc; use npx ultracite fix / npx ultracite check (or root npm run fix / npm run check) so config resolution matches the hook. The oxlint . / oxfmt . scripts in apps/web/package.json exist only for turbo’s per-workspace orchestration.
• No manual git hooks. ultracite init writes lefthook.yml and a prepare: lefthook install script; husky or another hook manager double-runs or skips fixes.
• Add --no-error-on-unmatched-pattern to the generated lefthook.yml. ultracite init writes one job globbing js,jsx,ts,tsx,json,jsonc,css, but oxlint lints neither JSON nor CSS and exits 1 when handed only those, so a dependency bump or a CSS-only commit fails the hook outright. Ultracite passes unknown options through to the linter, so npx ultracite fix --no-error-on-unmatched-pattern {staged_files} clears it in one flag, and oxfmt still formats the file. Splitting the job in two works as well but says the same thing twice.
• No app dependencies in the root package.json (root holds only turbo and ultracite); they break workspace isolation and turbo cache keys.
• Never run npx shadcn@latest add @blode/... before npx shadcn@latest registry add @blode=...; the unregistered namespace makes the add fail.
• Never import from lucide-react; blode-icons-react is Blode UI’s icon library and mixed imports bundle two icon sets. Replace any generated lucide-react import paths.
• Never create apps/web/ by hand. Scaffold at the root first, then move it in Phase 6; hand-building skips create-next-app defaults (Tailwind wiring, alias config).
• Check the Vercel Root Directory before dashboard deploys. On a 404 or wrong app, set Root Directory to apps/web in Settings > General.

Skill Handoffs