nextjs-starter

Next.js Starter Scaffolder

Scaffolds a complete, opinionated Next.js project with interactive customization. Generates project structure, installs dependencies, configures tooling, writes architecture rules in CLAUDE.md, and makes an initial commit.

Execution Flow

6 phases executed sequentially:

1. Interactive questions (project name, package manager, extras, MCPs)
2. Base scaffold via create-next-app
3. Configuration (shadcn/ui, Prettier, ESLint, extras)
4. Folder structure (hybrid: layer-based global + feature-based domain)
5. Rules files (CLAUDE.md + .mcp.json)
6. Verification + initial commit

---

Phase 1: Interactive Questions

Ask the user 4 questions using AskUserQuestion. Store the answers as variables for use in later phases.

Q1 — Project Name

AskUserQuestion(
  question: "What is the name of your project?",
  type: "free_text"
)

Store as PROJECT_NAME.

Q2 — Package Manager

AskUserQuestion(
  question: "Which package manager would you like to use?",
  type: "single_select",
  options: [
    { value: "pnpm", label: "pnpm (recommended)" },
    { value: "npm",  label: "npm" },
    { value: "bun",  label: "bun" }
  ]
)

Store as PM. Derive the following variables from PM:

PM	PM_RUN	PM_DLX	PM_CREATE	PM_FLAG
pnpm	pnpm	pnpm dlx	pnpm create	--use-pnpm
npm	npm run	npx	npx	--use-npm
bun	bun	bunx	bunx	--use-bun

Q3 — Extras

AskUserQuestion(
  question: "Which extras would you like to include?",
  type: "multi_select",
  options: [
    { value: "husky",       label: "husky + lint-staged (recommended)" },
    { value: "commitlint",  label: "commitlint (recommended)" },
    { value: "editorconfig",label: ".editorconfig (recommended)" },
    { value: "vscode",      label: "VS Code settings (recommended)" },
    { value: "env_example", label: ".env.example (recommended)" }
  ]
)

Store as EXTRAS (list of selected values).

Q4 — MCPs

AskUserQuestion(
  question: "Which MCPs would you like to configure? (Context7 is always included)",
  type: "multi_select",
  options: [
    { value: "context7",       label: "Context7 (always included)" },
    { value: "figma",          label: "Figma MCP" },
    { value: "browser_preview",label: "Browser Preview" },
    { value: "other",          label: "Other (you will be prompted for details)" }
  ]
)

Store as MCPS (list of selected values). context7 is always included regardless of selection. If other is selected, ask a follow-up free-text question to capture the additional MCP details.

---

Phase 2: Base Scaffold

0. Verify package manager availability

Before proceeding, check if the selected package manager (PM) is installed:

command -v {PM}

If the command is not found (exit code ≠ 0) and PM is pnpm or bun:

1. Ask the user for confirmation:

   AskUserQuestion(
     question: "{PM} is not installed. Would you like me to install it?",
     type: "single_select",
     options: [
       { value: "yes", label: "Yes, install {PM}" },
       { value: "no",  label: "No, switch to npm instead" }
     ]
   )
   

2. If yes: install the package manager:
   • pnpm: npm install -g pnpm
   • bun: curl -fsSL https://bun.sh/install | bash
3. If no: set PM to npm and re-derive all PM variables (PM_RUN, PM_DLX, PM_CREATE, PM_FLAG).

If PM is npm, skip this check — npm is always available with Node.js.

1. Run create-next-app

{PM_CREATE} next-app {PROJECT_NAME} --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" {PM_FLAG}

Then cd into the project directory:

cd {PROJECT_NAME}

2. Set Node.js version

Detect the current Node.js version:

node -v

Store the output (e.g., v22.14.0) as NODE_VERSION (without the v prefix → 22.14.0). Extract the major version as NODE_MAJOR (e.g., 22).

Write .nvmrc at the project root:

{NODE_MAJOR}

Add the engines field to package.json:

"engines": {
  "node": ">={NODE_MAJOR}"
}

3. Replace src/app/page.tsx

Write this exact content:

export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-center">
      <h1 className="text-4xl font-bold">Welcome</h1>
    </main>
  );
}

4. Clean src/app/globals.css

Keep only Tailwind directives and CSS variables. Remove all other default styles generated by create-next-app.

5. Remove default images from public/

Delete any default images (e.g., next.svg, vercel.svg) from the public/ directory.

---

Phase 3: Configuration

Core Configuration

shadcn/ui

Initialize shadcn/ui (choose style: default, base color: neutral, CSS variables: yes):

{PM_DLX} shadcn@latest init

Add the button component:

{PM_DLX} shadcn@latest add button

Prettier

Install Prettier and the Tailwind plugin:

{PM} add -D prettier prettier-plugin-tailwindcss

Write .prettierrc:

{
  "semi": true,
  "singleQuote": true,
  "trailingComma": "all",
  "tabWidth": 2,
  "printWidth": 80,
  "plugins": ["prettier-plugin-tailwindcss"]
}

Add a format script to package.json:

"format": "prettier --write ."

TypeScript

Verify tsconfig.json has "strict": true and the @/* path alias. create-next-app generates these — just confirm they are present.

ESLint

Detect the ESLint config format:

• Next.js 15+ uses flat config: eslint.config.mjs
• Older versions use legacy: .eslintrc.json

Extend the detected config with import ordering rules.

Tailwind

Detect Tailwind version:

• v4: CSS-based config — @theme block lives in globals.css. Configure the shadcn theme there.
• v3: File-based config — tailwind.config.ts. Configure the shadcn theme in that file.

---

Conditional Extras

Apply only the extras present in EXTRAS.

husky + lint-staged (if husky in EXTRAS)

Detect husky version and initialize accordingly:

• v9+: {PM_DLX} husky init
• v8: {PM_DLX} husky-init

Configure .husky/pre-commit to run:

{PM_DLX} lint-staged

Write .lintstagedrc.json:

{
  "*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
  "*.{json,md,css}": ["prettier --write"]
}

commitlint + commitizen (if commitlint in EXTRAS)

{PM} add -D @commitlint/cli @commitlint/config-conventional commitizen cz-conventional-changelog

Write commitlint.config.js:

module.exports = { extends: ['@commitlint/config-conventional'] };

Add commitizen config to package.json:

"config": {
  "commitizen": {
    "path": "cz-conventional-changelog"
  }
}

Add a commit script to package.json:

"commit": "cz"

If husky is also selected, add a commit-msg hook that runs commitlint.

.editorconfig (if editorconfig in EXTRAS)

Write .editorconfig:

root = true

[*]
indent_style = space
indent_size = 2
charset = utf-8
end_of_line = lf
trim_trailing_whitespace = true
insert_final_newline = true

VS Code (if vscode in EXTRAS)

Write .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.quickSuggestions": {
    "strings": true
  },
  "css.validate": false,
  "tailwindCSS.experimental.classRegex": []
}

Write .vscode/extensions.json:

{
  "recommendations": [
    "bradlc.vscode-tailwindcss",
    "esbenp.prettier-vscode",
    "dbaeumer.vscode-eslint"
  ]
}

.env.example (if env_example in EXTRAS)

Write .env.example:

NEXT_PUBLIC_APP_URL=http://localhost:3000
DATABASE_URL=
NEXT_PUBLIC_API_URL=

---

Phase 4: Folder Structure

Run these commands to create the project layout:

mkdir -p src/components/shared src/features src/hooks src/lib src/types
touch src/components/shared/.gitkeep src/features/.gitkeep src/hooks/.gitkeep src/types/.gitkeep

Note: src/components/ui/ and src/lib/utils.ts already exist — they were created by shadcn init in Phase 3. Do not recreate or modify them.

---

Phase 5: Rules Files

CLAUDE.md

Write CLAUDE.md at the project root with the following content, substituting {PROJECT_NAME}, {PM}, {PM_RUN}, and {PM_DLX}:

# {PROJECT_NAME}

## Stack
Next.js (App Router), TypeScript, Tailwind 4, shadcn/ui, {PM}

## Architecture Rules

### Folder Structure
- `app/` - ONLY routes, layouts, loading, error. Zero business logic
- `components/ui/` - Managed by shadcn CLI. NEVER create/edit manually
- `components/shared/` - Reusable components, ALWAYS composed from ui/
- `features/<name>/` - Self-contained: components/, hooks/, lib/, types/
- `lib/` - Pure functions, clients, configs. No React components
- `hooks/` - Global hooks. Feature hooks live in features/<name>/hooks/
- `types/` - Types shared between features

### Component Rules
- Every visual component MUST use primitives from components/ui/
- NEVER use native <button>, <input>, <select> - use shadcn
- Add new ui components: `{PM_DLX} shadcn@latest add <name>`
- Components MUST be reusable. Extract when used 2+ times
- Props typed with interfaces, never any

### Code Rules
- Path aliases: use @/ for all imports (never ../../../)
- Exports: named exports only (never default export except pages)
- Server Components by default. Use "use client" only when necessary
- Pure functions in lib/. Side effects isolated in hooks

### Commit Messages (Conventional Commits)
- Format: `<type>(<scope>): <description>`
- Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
- Scope is optional but recommended (e.g., `feat(auth): add login page`)
- Description: imperative mood, lowercase, no period at end
- Breaking changes: add `!` after type/scope (e.g., `feat!: remove legacy API`)
- Use `{PM_RUN} commit` for interactive commit wizard (commitizen)

## Required Skills
- USE superpowers:brainstorming BEFORE creating any new feature
- USE frontend-design when creating visual components and pages
- USE superpowers:writing-plans for features touching more than 2 files
- USE superpowers:verification-before-completion before declaring tasks done

## Commands
- `{PM_RUN} dev` - dev server
- `{PM_RUN} build` - production build
- `{PM_RUN} lint` - ESLint
- `{PM_RUN} format` - Prettier
- `{PM_RUN} commit` - interactive commit (commitizen)

.mcp.json

Write .mcp.json at the project root. Context7 is always included:

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

For each MCP in MCPS, extend mcpServers:

• figma (if figma in MCPS): add entry:

  "figma": {
    "command": "npx",
    "args": ["-y", "@anthropic-ai/figma-mcp@latest"]
  }
  

• browser_preview (if browser_preview in MCPS): inform the user that Browser Preview is configured in Claude Code settings, not in .mcp.json. No entry needed here.

• other (if other in MCPS): use the command/args captured from the follow-up question in Q4 and add the entry to .mcp.json.

---

Phase 6: Verification + Initial Commit

1. Build check

{PM_RUN} build

If it fails, read the error output, fix the issues, and retry. Maximum 3 attempts. Stop and report to the user if it still fails after 3 attempts.

2. Lint check

{PM_RUN} lint

If it fails, read the error output, fix the issues, and retry. Maximum 3 attempts. Stop and report to the user if it still fails after 3 attempts.

3. Initial git commit

Initialize a git repo if one does not already exist:

git init

Stage all files and create the initial commit:

git add .
git commit -m "feat: scaffold project with Next.js, Tailwind 4, shadcn/ui

- App Router with TypeScript strict mode
- shadcn/ui component library (Radix + Tailwind)
- Prettier + ESLint configured
- Opinionated folder structure (hybrid: layer + feature)
- CLAUDE.md with architecture rules
- MCP configuration (Context7 + extras)"

4. Print summary

Project {PROJECT_NAME} created successfully.
- X files generated
- Build: OK | Lint: OK
- Extras: {list of extras}
- MCPs: {list of MCPs}
- Initial commit created

Next step: cd {PROJECT_NAME} && {PM_RUN} dev