Next.js Scaffolding Skill

Next.js Scaffolding Skill

Version: 1.0.0 Owner: Architecture Department Used By: Scaffolder Agent

---

Purpose

Provide patterns and standards for scaffolding Next.js projects with consistent structure, configuration, and tooling.

---

Framework Standard

All projects use Next.js (App Router) with the following stack:

• Framework: Next.js 14+ (App Router)
• Language: TypeScript (strict mode)
• Styling: Tailwind CSS
• UI Components: shadcn/​ui
• Database: Supabase
• Auth: Supabase Auth
• Validation: Zod

---

Project Structure

/​project-name/
├── app/                        # Next.js App Router
│   ├── (auth)/                 # Auth-required routes (grouped)
│   │   ├── dashboard/
│   │   │   └── page.tsx
│   │   └── layout.tsx
│   ├── (public)/               # Public routes (grouped)
│   │   ├── page.tsx            # Home page
│   │   └── layout.tsx
│   ├── api/                    # API routes
│   │   └── v1/
│   ├── layout.tsx              # Root layout
│   └── globals.css
├── components/                 # Shared components
│   ├── ui/                     # shadcn/​ui components
│   └── [feature]/              # Feature-specific components
├── lib/                        # Shared utilities
│   ├── supabase/
│   │   ├── client.ts           # Browser client
│   │   ├── server.ts           # Server client
│   │   └── middleware.ts       # Auth middleware
│   ├── utils.ts                # General utilities
│   └── validations/            # Zod schemas
├── types/                      # TypeScript types
│   ├── database.ts             # Generated Supabase types
│   └── index.ts
├── public/                     # Static assets
├── supabase/                   # Supabase config
│   ├── migrations/
│   └── seed.sql
├── .env.local                  # Local environment
├── .env.example                # Environment template
├── .gitignore
├── next.config.js
├── package.json
├── tailwind.config.ts
├── tsconfig.json
└── README.md

---

Required Configuration Files

package.json (minimal)

{
  "name": "project-name",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "typecheck": "tsc --noEmit"
  }
}

tsconfig.json (strict)

{
  "compilerOptions": {
    "strict": true,
    "target": "ES2017",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "forceConsistentCasingInFileNames": true,
    "noFallthroughCasesInSwitch": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [{ "name": "next" }],
    "paths": {
      "@/​*": ["./​*"]
    }
  },
  "include": ["next-env.d.ts", "**/​*.ts", "**/​*.tsx", ".next/​types/​**/​*.ts"],
  "exclude": ["node_modules"]
}

.env.example

NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=

---

Scaffolding Checklist

1. Create project directory
2. Initialize package.json
3. Install dependencies
4. Configure TypeScript (strict mode)
5. Configure Tailwind CSS
6. Set up shadcn/​ui
7. Create directory structure
8. Set up Supabase client files
9. Create .env.example
10. Create .gitignore
11. Create README.md

---

Repo Style

Repo style (monorepo vs single-repo) is determined by Company Head in PRODUCT_SPEC.md.

• Single Repo: Standard structure above
• Monorepo: Use Turborepo with /​apps/ and /​packages/ structure

---

Commands

---

Stop Conditions

STOP and escalate if:

• PRODUCT_SPEC.md doesn't specify repo style
• Required dependencies conflict
• Framework version requirements unclear

---

Skill Version: 1.0.0