Scaffold Nextjs

Scaffold Next.js

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 with ultracite/oxlint/shadcn, 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).

The references encode the house stack and dependency order. Verify version-sensitive flags against the installed CLI and bundled documentation; update a proven incompatible template rather than forcing stale flags. Where a Next.js question comes up that the references do not answer, read the bundled docs at node_modules/next/dist/docs/ in the app (they match the installed version) rather than training data.

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 and icons
- [ ] Phase 4: Install Agentation
- [ ] Phase 5: Install Ultracite
- [ ] Phase 5.1: Enable ultracite/oxlint/shadcn
- [ ] 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 on the port reported by the server. Use a free task-owned port when 3000 is occupied.

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 and icons

Blode UI section of references/app-setup.md: shadcn init, register the @blode namespace, set iconLibrary in components.json, install blode-icons-react, 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: run ultracite@latest init with the exact flags listed, including --js-plugins @shadcn/lint (Ultracite ≥ 7.12). Verify with npx ultracite fix and npx ultracite check. The lefthook.yml it writes is temporary; Phase 6 replaces it with a root-level one.

Phase 5.1: Enable ultracite/oxlint/shadcn

ultracite/oxlint/shadcn section of references/app-setup.md: confirm init wrote import shadcn from "ultracite/oxlint/shadcn" into extends alongside core/next/react. If it did not, add that import (and jsPlugins: shadcn.jsPlugins). Do not hand-roll jsPlugins: ["@shadcn/lint"] or a starter-only no-restyle rule. The preset already turns shadcn/no-restyle off inside **/components/ui/**; add a matching override only when aliases.ui is a different path.

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, lefthook.yml, knip.json, and .gitignore from the templates. Delete apps/web/lefthook.yml; git only reads the copy next to .git.
2. Update apps/web/package.json scripts to the turbo-compatible block and remove its prepare script (the root one installs the hooks).
3. Verify apps/web/next.config.ts still has reactCompiler: true, cacheComponents: true, and partialPrefetching: true.
4. Write the root AGENTS.md from the template. Keep the Phase 5.1 design-system lint paragraph in apps/web/AGENTS.md outside the Next-managed markers, including ultracite fix / ultracite fix --codex.
5. Run npm install from the root, then npm run dev once from the coding agent's shell. When Next 16.3 detects a coding agent in the environment it appends its managed nextjs-agent-rules block to apps/web/AGENTS.md (some generators also create a CLAUDE.md wrapper). Commit AGENTS.md and remove any duplicate CLAUDE.md wrapper. From a plain terminal nothing is written; that is fine, the block arrives on the agent's first run.
6. Verify npm run check, npm run build, and npx lefthook run pre-commit --all-files pass from the root, then npm run start -w web and load the home page from the production build.

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

From references/deploy-and-launch.md: add the CI workflow, set metadataBase to https://{{domain}}, register the site with Search Console and Bing, add security.txt, the favicon package, and the OG image, 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' --include='*.yml' .

A {{name}} left in package.json fails npm install (invalid-name error); a {{domain}} left in metadata ships broken OG URLs. Two placeholders in the root package.json template are not gathered in Phase 1: {{ultracite_version}} is copied from the ultracite entry that ultracite init wrote into apps/web/package.json, and {{npm_version}} is the output of npm --version.

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.