A production-grade Next.js 16 boilerplate. Type-safe end-to-end, tested by default, hardened for production, and wired into the Claude Code asset suite from Everything Claude Code (ECC).
Bring an idea — the foundation is done.
Every Next.js project re-litigates the same decisions on day one: which UI primitives, which form library, how to validate env vars, where state lives, how to wire CI, how to keep AI assistants useful. This repo ships a single opinionated answer to each, picked from what's actually working in production in 2026.
| Layer | Choice |
|---|---|
| Framework | Next.js 16.2 (App Router, Turbopack default) |
| UI runtime | React 19.2 with the React Compiler (babel-plugin-react-compiler) |
| Language | TypeScript 5 (strict) |
| Styling | Tailwind CSS 4 (@tailwindcss/postcss) |
| Components | shadcn/ui-style primitives on top of Radix |
| State | Zustand 5 for cross-feature client state |
| Forms | React Hook Form + Zod + Server Actions |
| Validation | Zod schemas (shared client + server) |
| Env validation | @t3-oss/env-nextjs (build fails on missing vars) |
| Icons | lucide-react |
| Toasts | sonner |
| Testing (unit) | Vitest 2 + Testing Library + jsdom (80 % coverage) |
| Testing (E2E) | Playwright 1.49 (Chrome / Firefox / Safari) |
| Linting | ESLint 9 (flat config, eslint-config-next) |
| Formatting | Prettier 3 |
| Git hooks | husky 9 + lint-staged + commitlint (conventional commits) |
| Runtime / PM | Bun 1.3 |
| Security | AgentShield (ecc-agentshield) + NEXT_PUBLIC_* guard hook |
| AI tooling | Claude Code + 12 agents / 13 commands / 14 skills curated from ECC |
bun install
cp .env.example .env.local # fill in NEXT_PUBLIC_SITE_URL + NEXT_PUBLIC_APP_NAME
bun dev # http://localhost:3000For end-to-end testing:
bunx playwright install # one-time browser download
bun run test:e2eVisit the showcase routes to see every pattern in action:
| Path | What it shows |
|---|---|
/ |
Landing page (hero + feature grid + opt-in extras callout) |
/examples/components |
Visual gallery of every UI primitive |
/examples/forms |
React Hook Form + Zod + Server Action contact form |
/examples/data-fetching |
Server Component ISR fetch alongside a polling client |
/api/health |
JSON health endpoint |
/api/contact |
POST endpoint with Zod-validated body |
| Command | Purpose |
|---|---|
bun dev |
Next.js dev server with Turbopack (:3000) |
bun run build |
Production build |
bun run start |
Production server |
bun run lint / lint:fix |
ESLint |
bun run type-check |
tsc --noEmit |
bun run test / test:watch / test:coverage |
Vitest (80 % coverage threshold) |
bun run test:e2e |
Playwright (boots bun dev automatically) |
bun run format / format:check |
Prettier write / check |
bun run security:scan / security:fix |
AgentShield |
src/
├── app/ App Router
│ ├── layout.tsx Root layout (metadata, ThemeProvider, Toaster, site chrome)
│ ├── page.tsx Landing page (showcase)
│ ├── globals.css Tailwind 4 + design tokens + dark variant
│ ├── loading.tsx Suspense fallback
│ ├── error.tsx Route-level error boundary
│ ├── not-found.tsx 404
│ ├── sitemap.ts Dynamic sitemap
│ ├── robots.ts Dynamic robots.txt
│ ├── manifest.ts PWA manifest
│ ├── actions/contact.ts Server Action (Zod-validated)
│ ├── api/
│ │ ├── health/route.ts GET health check
│ │ └── contact/route.ts POST contact form
│ └── (examples)/examples/
│ ├── layout.tsx Examples nav
│ ├── components/page.tsx UI primitives gallery
│ ├── forms/ RHF + Zod + Server Action form
│ └── data-fetching/ Server Component + polling client
├── components/
│ ├── ui/ shadcn-style primitives (button, input, card, dialog, …)
│ ├── layout/ ThemeProvider, ThemeToggle, SiteHeader/Footer, Container
│ └── error-boundary.tsx Class-based React error boundary
├── hooks/ useDebounce, useMediaQuery, useMounted, useLocalStorage, …
├── lib/
│ ├── utils.ts cn()
│ ├── format.ts Date / currency / number formatters
│ ├── fetcher.ts Typed fetch wrapper with Result<T> return
│ ├── logger.ts createLogger() structured logger
│ └── validations/ Zod schemas shared client + server
├── stores/use-theme-store.ts Canonical Zustand store (persist + skipHydration)
├── env.ts Runtime env validation (@t3-oss/env-nextjs)
└── test/setup.ts Vitest + jest-dom + cleanup
middleware.ts Security headers
tests/e2e/ Playwright specs
docs/ Architecture, auth-setup, db-setup, deployment, styling
.claude/ Agents, commands, skills, rules, hooks
.github/ CI workflow + issue/PR templates
.husky/ Pre-commit + commit-msg hooks
.vscode/ Workspace settings + recommended extensions
These are real decisions — pick when you need them. Each has a one-page recipe under docs/:
- Auth — see
docs/auth-setup.md(NextAuth v5, Clerk, Lucia) - Database / ORM — see
docs/db-setup.md(Prisma, Drizzle, Supabase) - Email, payments, analytics, monitoring, i18n
Each opt-in is a small patch on top of this base, not a rip-out-and-replace.
The starter is designed for AI-assisted development. The
.claude/ directory ships an opinionated subset of ECC: 12 agents, 13 slash commands, 14 skills, 23 rule
files, and the NEXT_PUBLIC_* secret-guard hook.
Most-used flows:
/plan— produce an implementation plan before writing code./feature-dev— guided feature development./tdd-workflow— TDD-enforced bug fix / feature./code-review— review the current diff or a PR./build-fix— detect build errors and fix iteratively./security-scan— AgentShield scan./ecc-guide— interactive navigator for ECC assets.
Read CLAUDE.md for the full workflow and AGENTS.md for the agent roster.
docs/architecture.md— layout, state boundary, data fetching prioritydocs/styling.md— Tailwind 4 tokens, dark mode, variantsdocs/auth-setup.md— three opt-in auth recipesdocs/db-setup.md— three opt-in DB recipesdocs/deployment.md— Vercel / Cloudflare / DockerCONTRIBUTING.md— branching, commits, workflowSECURITY.md— vulnerability reportingCHANGELOG.md— release notes
MIT — Copyright (c) 2026 Khoi Pham.