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 are 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 do not 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 is a safe default from its perspective — client components always work, server components sometimes fail if you accidentally use browser APIs.
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 are on App Router, tell Claude you are using Route Handlers (app/api/route.ts), not the old API Routes (pages/api) format. The patterns look similar but are not 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. 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.
The Cursor Rules for Claude Code includes a Next.js rule set — App Router defaults, server component preferences, and the data fetching patterns that work. $19.
Top comments (0)