CLAUDE.md for Next.js

What makes Next.js unique?

Next.js App Router projects involve a mix of Server Components (default) and Client Components (denoted by "use client"). Without explicit rules inside CLAUDE.md, an AI assistant will often:

• Add "use client" directives globally, breaking SSR optimizations.
• Write standard React hooks inside Server Components, resulting in runtime compile errors.
• Mix up App Router layout boundaries and route handler formats.

The template below provides clear rules to prevent these common mistakes.

The Next.js CLAUDE.md Template

Copy the file below into your root CLAUDE.md:

# Build and Test Commands
- Build: `npm run build`
- Dev server: `npm run dev`
- Test: `npm run test`
- Test single file: `npm run test -- [filename]`
- Lint: `npm run lint`

# Code Style Guidelines
- Next.js: Use App Router conventions (`app/` directory).
- React Components: Default to Server Components; only add `"use client"` at the very top if active event listeners, state, or client hooks (useState, useEffect) are required.
- TypeScript: Enforce strict typings. Avoid using `any`.
- Styling: Use Tailwind CSS utility classes in markup. Follow the design system spacing and color tokens.
- APIs: Place route handlers under `app/api/.../route.ts` using native request/response typing.
- Formatting: 2 spaces indent, semi-colons required, double quotes for JSX strings.

# Project Architecture & Directories
- Page routes: `app/[route]/page.tsx`
- Layout shells: `app/layout.tsx` or nested `app/[route]/layout.tsx`
- Component directories: `src/components/` for shared components, or nested `_components/` under route subfolders.
- Utility library: `src/lib/` or `src/utils/`
- Ignore patterns: Do not index or modify `.next/`, `node_modules/`, or build outputs.

Key Layout Declarations Explained

• Server vs Client Boundary: The rule explicitly tells Claude to default to Server Components. It will only add "use client" when it specifically needs state hooks or click event handlers.
• Route Handlers: Restricting API handlers to route.ts and using native NextRequest and NextResponse prevents the assistant from attempting to write old-style Pages Router handlers.
• Build & Test Map: Linking the commands ensures Claude Code can verify that its edits compile correctly before completing its task.

Common Pitfalls for Next.js

• Failing to lock build outputs: Without ignore rules, Claude Code may attempt to search inside the compiled .next/ output directory, bloating its context and generating errors.
• Component splitting: Prevent Claude from creating monolithic components by enforcing that components are split into subfiles once they exceed 200 lines.