SKILL.md

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

code

/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)

json

{
  "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)

json

{
  "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

code

NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=

Scaffolding Checklist

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

Command	Purpose
`npx create-next-app@latest`	Initialize Next.js
`npx shadcn-ui@latest init`	Initialize shadcn/ui
`npm run dev`	Start dev server
`npm run build`	Build for production
`npm run lint`	Run ESLint
`npm run typecheck`	Run TypeScript check

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