# Claude Code for Next.js: A Practical Developer Guide

URL: https://agentvera.dev/en/blog/claude-code-for-nextjs/ · Published: 2026-11-01

Use Claude Code in a Next.js project: CLAUDE.md setup, App Router and Pages Router workflows, testing with Vitest/Jest and Playwright, and multi-agent runs.

**In short:**

- Claude Code works well for Next.js when you encode routing, component boundaries, and test commands in CLAUDE.md.
- Keep the agent in small, verifiable steps and always run lint, typecheck, and tests before accepting changes.
- Watch server/client boundary mistakes, stale cache assumptions, and route handler validation when Claude Code edits Next.js code.

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](/en/agents/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](/en/blog/claude-code-best-practices/).

## 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:

```markdown
# 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](/en/blog/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](/en/blog/run-multiple-claude-code-agents/) 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.

## Frequently asked questions

**Can Claude Code build a complete Next.js app from scratch?** It can scaffold routes, pages, route handlers, and tests, but you should still define conventions in CLAUDE.md and review server/client boundaries. Treat it as a fast pair programmer rather than a replacement for architecture decisions.

**How do I configure Claude Code for an existing Next.js project?** Add a CLAUDE.md at the project root with build, lint, and test scripts, router conventions, and rules about "use client", caching, and route handlers. Then run claude in the project root.

**Does Claude Code understand Next.js App Router and Pages Router?** It understands both routers when the project context is clear, but it can mix idioms if you don’t state which router is used. CLAUDE.md should specify app/ or pages/ and the corresponding data-fetching functions.

**Can Claude Code run my Next.js tests and build?** Yes, it can run package manager scripts such as pnpm test, pnpm lint, and pnpm build, read the failure output, and iterate. For user flows, point it at existing Playwright tests and ask it to fix failures rather than skipping them.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/