AI-First Next.js Boilerplate

Stop prompting. Start shipping.

The only Next.js boilerplate where Claude Code, Cursor, Gemini CLI, Kiro, Copilot, and Windsurf all produce identical, production-grade code — without custom prompting.

Get Started · Why This Exists · Features · Star History

The Problem

You open Cursor, type "create a user profile page," and get:

• A file in the wrong folder
• useState for form fields instead of react-hook-form
• Raw fetch() instead of your HTTP client
• console.log everywhere
• No Zod validation, no error boundaries, no types

You spend more time fixing AI output than writing code yourself.

This boilerplate solves that. Every AI tool reads the same rules, follows the same architecture, and produces code that passes your linting, type-checking, and code review — on the first try.

Why Developers Are Switching

What You Get

AI-First Development — The Core Differentiator

One rule file. Six AI tools. Zero drift.

Every AI coding assistant in your team reads the same architecture rules from a single source (.ai/rules.md), auto-synced to each tool's config format:

What this means in practice: Two developers — one using Cursor, one using Claude Code — generate code that looks like it was written by the same person. No "fix the AI output" phase. No style wars. No architectural drift.

Every commit triggers a semantic impact analysis powered by a Tree-sitter knowledge graph:

• Detects which functions, components, and modules are affected
• Scores risk level of changes
• Flags architectural violations before they reach PR review
• Provides blast radius visualization

This isn't linting — it's structural understanding of your codebase.

Production-Grade Architecture

src/
  app/              Routes ONLY — pages, layouts, route handlers
  features/         Vertical slices — one folder per business domain
    [name]/
      _components/  Private UI (never imported outside feature)
      _hooks/       Private hooks
      adapters/     HTTP layer (calls shared/lib/xhr)
      schemas/      Zod schemas + derived types
      services/     Business logic
      actions/      next-safe-action server actions
      index.ts      PUBLIC barrel — the ONLY export surface
  shared/           Cross-cutting utilities
  server/           Server-only code (iron-session, etc.)

Hard rules enforced by ESLint:

• app/ imports ONLY from features/[name]/index.ts — never deep paths
• Features NEVER import from other features
• shared/ NEVER imports from features/ or app/
• Adapters use shared/lib/xhr.ts — never raw fetch()

Full-Stack Tech Stack

Security — Not an Afterthought

• CSP, HSTS, X-Frame-Options, X-Content-Type-Options configured out of the box
• import 'server-only' guard on server modules
• Zod validation at every API boundary
• Middleware-based route protection
• public/.well-known/security.txt for responsible disclosure
• No eval(), no dangerouslySetInnerHTML without DOMPurify

Testing — Mock Adapters, Never Services

npm run test          # Vitest with interactive UI
npm run test:check    # CI mode (exits with code)
npm run test:coverage # Coverage report (v8)
npx playwright test   # E2E tests

• Mock at the HTTP layer (adapters), never at the service layer
• @testing-library/react for behavior-driven component tests
• MSW v2 for network-level API mocking
• Convention: describe('[ServiceName]') > it('should [behavior] when [condition]')

Quality Gates — Every Commit

Husky runs automatically on every commit:

1. Biome — format + lint (sub-second)
2. ESLint — architectural rules (no console.log, no any, no cross-feature imports)
3. TypeScript — tsc --noEmit, zero errors
4. commitlint — enforces type(scope): description format
5. Code Review Graph — semantic impact analysis

If it doesn't pass the gates, it doesn't get committed. Period.

Quick Start

# Clone
git clone https://github.com/NoahDuongMaster/ai-first-nextjs-boilerplate.git
cd ai-first-nextjs-boilerplate

# Install
npm install

# Start dev server (Turbopack)
npm run dev

Open http://localhost:3000.

All AI tool configs are generated from a single source (.ai/rules.md):

./scripts/gen-ai-config.sh

This updates CLAUDE.md, .cursorrules, .windsurfrules, .github/copilot-instructions.md, .gemini/GEMINI.md, and .kiro/steering/ — keeping every AI tool in sync.

# Development (hot-reload, source maps)
npm run build:development && npm run start:development  # → :3001

# Staging (production build, staging env)
npm run build:staging && npm run start:staging          # → :3002

# Production (standalone, minimal image)
npm run build:production && npm run start:production    # → :80

Declared in src/shared/config/env.configuration.ts with Zod validation. Never use process.env directly.

All Scripts

Project Structure

.
├── .ai/rules.md                  Single source of truth for all AI rules
├── .claude/steering/             Claude Code steering rules
├── .cursorrules                  Cursor rules (auto-synced)
├── .windsurfrules                Windsurf rules (auto-synced)
├── .github/copilot-instructions  Copilot rules (auto-synced)
├── .gemini/                      Gemini CLI config + hooks
├── .kiro/steering/               Kiro steering rules
├── docker/                       Three-tier Docker setup
├── scripts/                      AI config sync + setup scripts
├── src/
│   ├── app/                      Next.js routes (zero business logic)
│   ├── features/                 Vertical slices by domain
│   ├── shared/                   Cross-cutting utilities
│   ├── server/                   Server-only code
│   └── __examples__/             Canonical patterns for AI reference
└── tests/                        Playwright E2E tests

Contributing

1. Fork the repo
2. Create a branch: feat(scope)/issue-123-description
3. Follow patterns in src/__examples__/
4. Pass all gates: npm run type-check && npm run lint && npm run test:check
5. Open a PR

Star History