CLAUDE.md for Next.js Apps
A battle-tested CLAUDE.md template for Next.js App Router projects.
A complete CLAUDE.md template for Next.js App Router projects: commands, server/client component rules, data-fetching conventions, styling system, and the guardrails that stop agents from breaking hydration or leaking server code to the client.
The template
# CLAUDE.md ## Project [Product name] — [one sentence on what it does]. Next.js App Router + TypeScript + Tailwind. Deployed on Vercel. ## Commands ```bash pnpm dev # dev server (Turbopack) pnpm build # production build — run before claiming work is done pnpm lint # ESLint + type checking pnpm test # unit tests (Vitest) ``` ## Architecture - `app/` — routes. Route groups: `(marketing)` public pages, `(app)` authed product - `components/ui/` — shadcn primitives, don't edit directly; `components/` — product components - `lib/` — data layer, helpers. Server-only modules import `server-only` ## Rules ### Server vs client - Components are Server Components by default. Add `"use client"` ONLY for interactivity (state, handlers, browser APIs) - Never import server-only modules (db, secrets) into client components — the build catches some of this but not all - Data fetching happens in Server Components or route handlers, never in useEffect ### Conventions - Named exports for components; file names kebab-case - Tailwind only — no CSS modules, no styled-components. Use the `cn()` helper for conditional classes - Forms: server actions with `useActionState`, zod validation on the server side always - Images via `next/image` with explicit dimensions ### Don't - Don't add new dependencies without asking — check if an existing dep covers it - Don't edit `components/ui/*` (generated); extend via wrapper components - Don't use `router.push` where a `<Link>` works - Don't suppress TypeScript errors; fix the type or ask ## Verification Before saying a task is done: `pnpm lint && pnpm build` must pass. For UI changes, describe what you verified in the browser.
How to use
- 1Copy to the root of your repo as CLAUDE.md and replace the bracketed placeholders.
- 2Delete rules that don't apply and add your project's real quirks — specificity is what makes it work.
- 3Keep it under ~150 lines; agents follow short, firm files better than exhaustive ones.
- 4Update it when the agent makes the same mistake twice — that's a missing rule.
Examples
Effect of the server/client rule
Input
Agent asked to add a like button to a server-rendered post page.
Output
Without the rule: agent often converts the whole page to a client component. With it: creates a small `LikeButton` client component, keeps the page server-rendered, wires a server action for the mutation.
Pro tips
- The Verification section has the highest impact-per-line — agents that know the definition of done finish work properly.
Frequently asked questions
What's the difference between CLAUDE.md and a skill?+
CLAUDE.md loads on every session in the repo — it's for always-true project context. Skills load on demand for specific task types. Project conventions go here; task procedures (like commit style) work better as skills.
How long should a CLAUDE.md be?+
Shorter than you think — 50–150 lines. Every line competes for the agent's attention; a 500-line file gets skimmed. Link to docs for depth instead of inlining everything.