CLAUDE.md for Next.js

Server Components vs client components, App Router structure, and env-var prefixes are exactly where agents go wrong in Next.js — a good CLAUDE.md names all three. Below is a complete, committable example for a typical Next.js project. To get one tailored to your dependencies and scripts, paste your manifest into the free generator (client-side, nothing uploaded) or run npx getagentready in your repo.

Complete example

# CLAUDE.md

This file guides Claude Code when working in this repository.

## Project

**example-next-app** — Stack: TypeScript, Next.js (App Router), pnpm, Vitest, ESLint, Prettier.

## Commands

- Install dependencies: `pnpm install`
- Run dev server: `pnpm dev`
- Build: `pnpm build`
- Run all tests: `pnpm test`
- Run a single test: `pnpm vitest run path/to/file.test.ts -t "test name"`
- Lint: `pnpm lint`
- Type-check: `pnpm typecheck`

## Testing

Tests use Vitest. Write or update tests alongside behavior changes; run the single-test command during iteration and the full suite before finishing.

## Conventions

- Use the App Router (`app/`) structure: `page.tsx` for routes, `layout.tsx` for shared chrome, `route.ts` for API endpoints.
- Components are Server Components by default — add `"use client"` only when the component needs state, effects, or browser APIs.
- Fetch data in Server Components or route handlers, not in client-side `useEffect`.
- Use `next/image` for images and `next/link` for internal navigation.
- Prefer small, focused changes; do not refactor unrelated code in the same change.
- Match the existing code style of the file you are editing over any global preference.
- Never commit secrets. `.env*` files are local-only.
- After making changes, run the test and lint commands above before considering work done.

## Gotchas

- Server Components cannot use hooks or event handlers; moving code between server/client contexts is the most common source of build errors.
- Environment variables are only exposed to the browser when prefixed with `NEXT_PUBLIC_`.
- `next dev` masks some production-only issues — verify SSR/streaming behavior with `next build && next start` before calling a change done.

<!-- generated with https://getagentready.dev -->

Going further

This is the generated baseline. The Agent-Ready Pro Pack includes a hand-tuned, deeper Next.js configuration — architecture guidance, testing strategy, common-task recipes — plus 12 workflow skills and enforcement hooks. See also the CLAUDE.md guide and AGENTS.md guide.