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 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 define-architecture), or choosing visual direction and palettes (use ui-design).

This is a low-freedom workflow. Commands live in the reference files and are exact: run them as written, in phase order. The reference files are the single source of truth for commands; do not reconstruct them 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 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 what was not provided):

Phase 2: Create Next.js app

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

Phase 3: Install Blode UI components

Follow the Blode UI section in references/app-setup.md: shadcn init, then register the @blode namespace, then add components. Registration must come before any add @blode/... call. Always use blode-icons-react for icon imports (never lucide-react).

Phase 4: Install Agentation

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

Phase 5: Install Ultracite

Follow the Ultracite section in 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 load references/turbo-configs.md and:

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 in the reference. 3. Verify apps/web/next.config.ts has reactCompiler: 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

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

Phase 8: Pre-launch checklist

Follow the favicon and OG image steps in references/deploy-and-launch.md, then run the validation checklist at the end of that file. The scaffold is done only when every validation item passes; "the site loads" is not sufficient evidence.

Placeholder Reference

All 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 makes npm install fail with an invalid-name error; a {{domain}} left in metadata ships broken OG URLs.

Gotchas

• Do not add a src/ directory. The scaffold uses --no-src-dir; introducing src/ later breaks the @/* alias and every shadcn component path.
• Do not add ESLint or Prettier. Ultracite owns lint and format via Oxlint + Oxfmt; a stray .eslintrc makes the editor disagree with the lefthook pre-commit hook.
• Do not run oxlint or oxfmt ad hoc; use npx ultracite fix / npx ultracite check (or npm run fix / npm run check at the root) so config resolution matches the hook. The oxlint . / oxfmt . scripts inside apps/web/package.json exist only so turbo can orchestrate per-workspace tasks.
• Do not configure git hooks manually. ultracite init writes lefthook.yml and a prepare: lefthook install script; adding husky or another hook manager double-runs or skips fixes.
• Do not put app dependencies in the root package.json. The root holds only turbo and ultracite; app deps at the root break workspace isolation and turbo cache keys.
• Do not run npx shadcn@latest add @blode/... before npx shadcn@latest registry add @blode=.... The unregistered namespace makes the add command fail.
• Do not import from lucide-react. blode-icons-react is the icon library for Blode UI; mixed imports bundle two icon sets. Replace any generated lucide-react import paths.
• Do not 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).
• Do not deploy from the dashboard without checking the Root Directory. If Vercel serves a 404 or the wrong app, set the project Root Directory to apps/web in Settings > General.

Skill Handoffs

App Setup Commands

Contents

• Phase 2: Create Next.js app
• Phase 3: Install Blode UI components
• Phase 4: Install Agentation
• Phase 4.1: Add Google Analytics (optional)
• Phase 5: Install Ultracite
• Phase 6 prep: Move into apps/web/

---

Phase 2: Create Next.js app

Run non-interactively with all flags:

npx create-next-app@latest {{name}} --typescript --tailwind --biome --react-compiler --app --no-src-dir --import-alias "@/*" --use-npm

This sets up: TypeScript, Tailwind CSS v4, Biome (a placeholder, replaced by Oxlint + Oxfmt via Ultracite in Phase 5), React Compiler, App Router, Turbopack (default in Next.js 16+), no src/ directory, @/* import alias, npm as package manager.

If running interactively, select "No, customize settings" at the defaults prompt, then choose:

• TypeScript: Yes
• Which linter: Biome (will be replaced by Oxlint + Oxfmt in Phase 5)
• React Compiler: Yes
• Tailwind CSS: Yes
• src/ directory: No
• App Router: Yes
• Import alias: @/*

After creation, verify:

cd {{name}}
npm run dev

Confirm the app loads at http://localhost:3000.

Phase 3: Install Blode UI components

Blode UI is a third-party shadcn/ui registry hosted at ui.blode.co. Use the hosted @blode namespace flow by default.

npx shadcn@latest init
npx shadcn@latest registry add @blode=https://ui.blode.co/r/{name}.json
npx shadcn@latest add @blode/button

Order matters: registry add must run before any add @blode/... call, otherwise the namespace is unknown and the add fails.

This creates:

• components.json: shadcn configuration plus the Blode registry mapping
• lib/utils.ts: cn() helper (clsx + tailwind-merge)
• components/ui/button.tsx: button from the ui.blode.co registry
• CSS variable updates in app/globals.css

Icon library requirement:

• Use blode-icons-react for all icon imports.
• If any generated file imports lucide-react, replace import paths with blode-icons-react.

Phase 4: Install Agentation

npm install agentation

Patch app/layout.tsx:

1. Add import at the top:

import { Agentation } from "agentation";

2. Add the component before </body>, wrapped in a dev-only guard:

{process.env.NODE_ENV === "development" && <Agentation />}

Full layout pattern:

import { Agentation } from "agentation";

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body
        className={`${geistSans.variable} ${geistMono.variable} antialiased`}
      >
        {children}
        {process.env.NODE_ENV === "development" && <Agentation />}
      </body>
    </html>
  );
}

Phase 4.1: Add Google Analytics (optional)

npm install @next/third-parties@latest

Patch app/layout.tsx:

import { Agentation } from "agentation";
import { GoogleAnalytics } from "@next/third-parties/google";

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body
        className={`${geistSans.variable} ${geistMono.variable} antialiased`}
      >
        {children}
        {process.env.NODE_ENV === "development" && <Agentation />}
      </body>
      <GoogleAnalytics gaId="G-XYZ" />
    </html>
  );
}

Replace "G-XYZ" with your GA4 measurement ID.

Phase 5: Install Ultracite

1. Delete the Biome config and dependency created by create-next-app:

rm biome.json
npm uninstall @biomejs/biome

2. Run Ultracite init non-interactively for Oxlint + Oxfmt + Lefthook:

npx ultracite@latest init \
  --linter oxlint \
  --frameworks next react \
  --integrations lefthook \
  --pm npm \
  --skip-install \
  --quiet

Notes on the flags:

• --frameworks takes space-separated values (next react), not commas. Comma-separated values fail validation.
• --skip-install lets you review the generated package.json changes before installing.
• Omit --quiet if you want to confirm the generated file list interactively.

This sets up:

• oxlint.config.ts: extends ultracite/oxlint/{core,next,react}
• oxfmt.config.ts: extends ultracite/oxfmt
• lefthook.yml: pre-commit hook running npx ultracite fix on staged JS/TS/JSON/CSS with stage_fixed: true
• Adds oxlint, oxfmt, lefthook to devDependencies and prepare: lefthook install to scripts

3. Install and verify:

npm install
npx ultracite fix     # oxfmt --write + oxlint --fix
npx ultracite check   # oxfmt --check + oxlint

Both pass with zero errors and the generated oxlint.config.ts needs no tuning. AGENTS.md is generated automatically with the Ultracite code-standards reference; create CLAUDE.md as a symlink or one-line @AGENTS.md reference.

Phase 6 prep: Move into apps/web/

From the parent directory of {{name}}:

mkdir -p {{name}}-turbo/apps
mv {{name}} {{name}}-turbo/apps/web
mv {{name}}-turbo {{name}}

The Next.js app is now at {{name}}/apps/web/.

Next: load references/turbo-configs.md and generate root config files in {{name}}/.

Deploy and Launch

Phase 7: GitHub setup

From the project root ({{name}}/):

git init
git add -A
git commit -m "initial commit"
git branch -M main
gh repo create {{repo}} --public --source=. --remote=origin --push

This uses the GitHub CLI (gh) to create the repo and push in one step. If gh is not available, use the manual approach:

git remote add origin https://github.com/{{repo}}.git
git push -u origin main

Phase 7: Vercel deployment

Using the Vercel CLI:

npx vercel --yes
npx vercel --prod

Or via the dashboard:

1. Go to vercel.com/new and add a new project. 2. Import the GitHub repo ({{repo}}). 3. Vercel auto-detects the turborepo and Next.js app in apps/web. 4. Deploy.

Then add custom domain: {{domain}} (via dashboard Settings > Domains, or npx vercel domains add {{domain}}).

If the deployment serves a 404 or the wrong app, set the project Root Directory to apps/web (dashboard Settings > General > Root Directory) and redeploy. Vercel does not always infer the app location in a fresh turborepo.

Verify: https://{{domain}} loads the default Next.js page.

Phase 8: Pre-launch checklist

Favicon

1. Open RealFaviconGenerator. 2. Generate a favicon package from your source image. 3. Place the generated files in apps/web/app/.

OG images

Create and place in apps/web/app/:

• opengraph-image.png (1200x630)
• twitter-image.png (1200x630)

Next.js App Router automatically serves these as OG and Twitter card images via file-based metadata conventions. Alternatively, generate images using code (.js, .ts, .tsx).

Skill handoffs

Run these skills in order after deployment:

1. optimise-seo: metadata, structured data, sitemap, robots, Core Web Vitals 2. ui-audit: accessibility, typography, interaction quality, craft polish 3. ui-animation: motion easing, timing, gestures, and review rules

Validation checklist

After all phases complete, verify:

• [ ] npm run dev starts successfully from project root (turbo runs apps/web)
• [ ] npm run build succeeds with no errors
• [ ] npm run check passes Ultracite checks
• [ ] npm run check-types passes TypeScript checks
• [ ] npx lefthook run pre-commit --all-files passes all hooks
• [ ] GitHub repo has the initial commit pushed
• [ ] Vercel deployment is live at {{domain}}
• [ ] Favicon appears in browser tab
• [ ] OG image renders in social card previews (use https://opengraph.xyz to test)

Turborepo Config Templates

Contents

• Root package.json
• turbo.json
• Root .gitignore
• knip.json
• apps/web/package.json scripts
• apps/web/next.config.ts

---

Root package.json

Create at {{name}}/package.json:

{
  "name": "{{name}}",
  "private": true,
  "packageManager": "npm@10.9.3",
  "workspaces": [
    "apps/*"
  ],
  "scripts": {
    "build": "turbo build",
    "dev": "turbo dev",
    "lint": "turbo lint",
    "lint:fix": "turbo lint:fix",
    "format": "turbo format",
    "format:check": "turbo format:check",
    "check-types": "turbo check-types",
    "check": "ultracite check",
    "fix": "ultracite fix"
  },
  "devDependencies": {
    "turbo": "^2",
    "ultracite": "^7.1.5"
  }
}

turbo.json

Create at {{name}}/turbo.json:

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "out/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {
      "dependsOn": ["^build"]
    },
    "lint:fix": {
      "cache": false
    },
    "format": {
      "cache": false
    },
    "format:check": {
      "dependsOn": ["^build"]
    },
    "check-types": {
      "dependsOn": ["^build"]
    }
  }
}

Root .gitignore

Create at {{name}}/.gitignore:

node_modules
out
dist
*.tgz

coverage
*.lcov

logs
*.log

.env
.env.development.local
.env.test.local
.env.production.local
.env.local

.eslintcache
.cache
*.tsbuildinfo

.idea
.DS_Store
.turbo
.vercel

.claude/
.cursor/
.vscode/

knip.json

Create at {{name}}/knip.json:

{
  "$schema": "https://unpkg.com/knip@5/schema.json",
  "ignore": [".vercel/**"]
}

Run dead-code analysis on demand with npx knip from the root (knip is not a devDependency; npx fetches it). Add workspace-specific entry points to knip.json as needed (e.g. for CLI apps or docs sites with custom entry files).

apps/web/package.json scripts

Update the scripts block in apps/web/package.json to include turbo-compatible commands:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "oxlint .",
    "lint:fix": "oxlint --fix .",
    "format": "oxfmt --write .",
    "format:check": "oxfmt .",
    "check-types": "tsc --noEmit"
  }
}

These script names match the tasks defined in turbo.json, allowing turbo to orchestrate them across workspaces. The oxlint/oxfmt invocations here are for turbo orchestration only; for ad-hoc lint or format runs use npx ultracite fix / npx ultracite check so config resolution matches the pre-commit hook. If the project adds a test runner later, add a matching test task to turbo.json at the same time.

apps/web/next.config.ts

Verify apps/web/next.config.ts has React Compiler enabled:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  reactCompiler: true,
};

export default nextConfig;

create-next-app generates this file when React Compiler is selected. Verify reactCompiler: true is present.