Claude Code for Next.js: what works and what to watch out for

Next.js has moved fast across versions — Pages Router to App Router, client components to server components, different data fetching patterns. Claude's training data includes all of them, which means it defaults to whichever pattern it saw most, not necessarily the one you're using.

Tell Claude which version and which router

Before any Next.js task: "This project uses Next.js 15 with the App Router. Use server components by default unless client state is required." Without this, Claude might write Pages Router patterns in an App Router project, or add 'use client' to components that don't need it.

Also tell it your data fetching approach. "We use React Query for client-side fetching and async server components for server-side fetching." Claude will follow this if you state it explicitly.

The 'use client' problem

Claude tends to add 'use client' more than necessary. It's a safe default from its perspective — client components always work, server components sometimes fail if you accidentally use browser APIs. So it defaults to client.

The issue: 'use client' turns off server component optimizations and can bloat your bundle. Add to your CLAUDE.md: "Do not add 'use client' unless the component uses useState, useEffect, or browser APIs. Prefer server components."

Route handlers vs API routes

If you're on App Router, tell Claude you're using Route Handlers (app/api/route.ts), not the old API Routes (pages/api) format. The patterns look similar but aren't identical. Claude uses the wrong one silently sometimes.

Server actions

Server actions are newer — Claude's handling of them is less consistent than its handling of route handlers. For server actions: be more specific in your prompt, verify the output carefully, and test them explicitly. The auth patterns around server actions are especially easy to get wrong.

What Claude handles well

Layout and page files. Metadata configuration. Static paths for dynamic routes. Loading and error states. These are well-represented in Claude's training and it gets them right with minimal prompting.

Middleware is also usually correct for standard use cases — auth redirects, locale detection, A/B testing patterns. Review the matcher config carefully though — Claude sometimes gets the pattern syntax wrong.