Claude Code for Next.js: A Practical Developer Guide

Claude Code is a terminal coding agent that reads your Next.js repo, edits files, runs commands, and reviews its own changes. For a Next.js project, run claude in the project root, add a CLAUDE.md with the commands and router conventions, and keep the agent in small verified steps. This guide covers App Router, Pages Router, server and client components, route handlers, and testing with Vitest, Jest, and Playwright.

Why Claude Code fits Next.js development

Next.js rewards exact context: route segments, layout nesting, server/client boundaries, caching behavior, and build-time validation. Claude Code can inspect the whole repo, trace imports, read tsconfig.json, eslint.config.*, and next.config.*, then make edits that respect those constraints. It is strongest when the project already has clear conventions—where files live, when a component must be a client component, how route handlers return responses, and which scripts verify the change. Because it can run pnpm lint, pnpm test, and pnpm build after each edit, it closes the loop between changing code and seeing a failing compiler or test. That makes it practical for day-to-day Next.js work rather than only generating snippets. For a broader checklist, see Claude Code best practices: a practical checklist.

Setting up CLAUDE.md for a Next.js project

Create or edit CLAUDE.md in the project root. Keep it short but specific to Next.js. Tell the agent the package manager, the scripts it should run, the router in use, and the rules that are easy to get wrong. Avoid generic instructions; list exactly what a new engineer would need to know before editing.

Here is a realistic example for an App Router project:

# CLAUDE.md

## Commands
- `pnpm dev` – start the development server
- `pnpm build` – production build; runs typecheck
- `pnpm lint` – ESLint
- `pnpm test` – Vitest unit/component tests
- `pnpm test:e2e` – Playwright end-to-end tests

## Folder conventions
- `app/` – App Router routes, layouts, pages, loading/error files, route handlers
- `components/` – shared React components; server components by default
- `lib/` – server-only utilities, data access, auth helpers
- `tests/` – Vitest tests; `e2e/` – Playwright specs

## Next.js rules
- Add `"use client"` only in components that need hooks, browser APIs, or event handlers.
- Keep data fetching in server components and route handlers; pass serializable props to client components.
- Use `next/link` for internal navigation and `next/image` for optimized images.
- In route handlers, validate input with Zod and return `NextResponse.json` with the correct status.
- Do not change `next.config.*`, middleware, or caching defaults without asking first.
- Keep page/layout `metadata` exports in server files only.

For a Pages Router project, replace app/ with pages/, pages/api/ for route handlers, and use getServerSideProps, getStaticProps, or getStaticPaths conventions. The same principle applies: make the agent’s default behavior match the codebase.

After adding CLAUDE.md, run claude in the project root and ask it to confirm the scripts and conventions before the first code change. That first turn catches ambiguity early.

Working in small verified steps

The reliable loop is: plan, make one small change, run the selected verification command, then review the diff. Do not ask for a large feature in one turn, because Next.js failures often appear only after type checking, linting, or a client/server boundary mistake.

Start with a concrete request and limit scope. Use plan mode before large refactors; see Claude Code plan mode for the workflow. After the agent edits files, run the relevant script—such as pnpm lint, pnpm test, or pnpm build—and inspect the diff with git diff before accepting.

Example prompts for typical Next.js tasks:

• Add a server component page at app/dashboard/page.tsx that fetches the current user from the auth helper, shows a loading state, and lists recent projects. Do not add client components.
• Create a route handler at app/api/users/route.ts with GET and POST. Validate the POST body with Zod and return 400 on invalid input.
• Convert components/ThemeToggle.tsx to a client component. Add "use client", use local state, and verify no server-only imports remain.
• Write a Vitest test for lib/validators.ts and a Playwright test for the login flow. Then run both and report failures.
• Fix the ESLint warning about <img> in app/products/[id]/page.tsx and replace it with next/image.

After each change, have the agent run the narrowest verification command first. If it passes, run pnpm build before merging. This catches type-only errors that linting and unit tests miss.

What Claude Code handles well in Next.js and what to review

Claude Code handles many Next.js tasks well, but the areas below need review because the framework splits execution between server and client.

| Area | What Claude Code handles well | Watch closely | | File-based routing | Creates page, layout, loading, error, and route handler files under the correct segment with typed params | Can place files under the wrong route group or mismatch params in nested layouts | | Server/client boundary | Keeps data fetching in server components and isolates "use client" leaves | May import server-only modules into a client component or pass non-serializable props | | Route handlers | Writes NextRequest/NextResponse handlers with status codes and basic validation | May miss auth, CORS, streaming, or request body edge cases | | Data fetching and caching | Uses fetch with next: { revalidate } and React cache where appropriate | May over-disable caching or refetch on the client unnecessarily | | Styling and images | Applies Tailwind classes and uses next/image for optimized images | Can break responsive layout or leave <img> tags that bypass optimization | | Testing | Adds Vitest/Jest unit tests and Playwright flows from existing patterns | May write brittle selectors or test implementation details instead of user flows |

For Pages Router work, watch getServerSideProps/getStaticProps edits closely: the agent may use App Router idioms or forget that pages/api handlers differ from App Router route handlers.

Testing and build verification with the agent

Treat verification as part of the agent’s turn, not an afterthought. After any code change, ask it to run only the relevant script. For a component or utility change, run pnpm test and pnpm lint. For a routing or server/client boundary change, add pnpm build. For user-facing flows, run pnpm test:e2e. If a Playwright test fails, ask the agent to read the failure output and fix the test or the code, not to skip the test.

Next.js adds another layer: next build performs type checking and can fail on TypeScript errors that unit tests never reach. Always run it before accepting a large change. If the project uses Jest instead of Vitest, replace the test command with the project’s Jest script; the loop stays the same.

Ask the agent to summarize what it changed and why before you accept the diff. If it changed next.config.*, middleware, or caching behavior, review that diff manually even if tests pass.

Parallel agents on one Next.js repo with AgentVera

When you run multiple Claude Code agents against one Next.js repo, uncoordinated changes to routes, layouts, and shared components can conflict quickly. AgentVera runs each coding agent in its own real terminal panel, and each agent can work in its own git worktree, so parallel changes stay isolated instead of overwriting files. After a turn ends, a second model reviews the code and links findings to file and line, which helps catch server/client boundary mistakes before they merge. Checkpoints let you undo a bad turn, and token budgets keep parallel Next.js work from consuming unbounded context. See how to run multiple Claude Code agents in parallel for more on parallel agent workflows.

Wrap-up

Claude Code becomes much more useful in a Next.js project once you put the project’s router conventions, scripts, and boundary rules into CLAUDE.md. Keep changes small, run lint, tests, and next build after each step, and review the diff for server/client mistakes. With that loop, it handles routing, route handlers, data fetching, and testing work well enough to be a daily coding agent rather than a one-shot code generator.