Next.js CLAUDE.md

A comprehensive CLAUDE.md for Next.js 15 App Router projects. Covers file conventions, server/client component rules, and common patterns.

CLAUDE.mddevelopmentnext.jsreactapp-routertypescript

by Build Ship Grow

next.js-claude.md.md

markdown

# CLAUDE.md — Next.js 15 App Router

## Stack
- Next.js 15, React 19, TypeScript
- App Router with Server Components by default
- Tailwind CSS for styling, shadcn/ui components

## Commands
```bash
pnpm dev          # Start dev server (Turbo)
pnpm build        # Production build
pnpm lint         # ESLint
pnpm test         # Vitest
```

## Conventions
- Use Server Components unless interactivity is needed
- Add "use client" only for hooks, event handlers, or browser APIs
- Server Actions for mutations — never expose raw API routes for form handling
- Path alias: `@/` maps to project root
- Colocate page-specific components in the route folder
- Shared components in `/components`, UI primitives in `/components/ui`

## File Naming
- `page.tsx` — route page (always Server Component)
- `layout.tsx` — shared layout wrapper
- `loading.tsx` — Suspense fallback
- `error.tsx` — error boundary ("use client" required)
- `not-found.tsx` — 404 UI

## Do NOT
- Import server-only code in client components
- Use `useEffect` for data fetching — use async Server Components
- Create API routes for mutations — use Server Actions instead