Next.js is one of the best frameworks to pair with Claude Code. The combination of file-based routing, Server Components, and TypeScript creates a codebase that Claude Code navigates and extends with high accuracy. This guide covers practical Next.js development workflows with Claude Code — App Router patterns, Server vs Client Components, API routes, and full-stack task execution.
Setting Up Claude Code for Next.js Projects
Your CLAUDE.md file is critical for Next.js projects because the App Router has architectural decisions that aren’t obvious from the code alone. Without good context, Claude will make poor decisions about what’s a Server Component vs Client Component, where to put data fetching, and how your auth works.
# Next.js App Router Project
## Stack
- Next.js 15 with App Router (not Pages Router)
- TypeScript 5, Tailwind CSS, Shadcn/ui
- Database: Neon PostgreSQL via Drizzle ORM
- Auth: Clerk
- Deployment: Vercel
## Key Architecture Decisions
- Fetch data in Server Components, pass to Client Components
- Client Components only for: user interactions, browser APIs, useEffect
- Use `"use client"` directive only when genuinely needed — not by default
- All DB access in server-side code only (never in Client Components)
- API routes in app/api/ only for: webhooks, external callbacks, mutations from client
- Prefer Server Actions for form submissions
## Route Structure
- (marketing) group: public pages, no auth required
- (app) group: authenticated, uses Clerk + middleware
## Never
- Access DB directly from Client Components
- Store secrets in client-side code
- Use the Pages Router — we're on App RouterSee the full CLAUDE.md setup guide for more on configuring project context.
App Router Patterns Claude Code Handles Well
Creating New Routes
Create a new route at /dashboard/analytics.
It should:
- Fetch analytics data from the database (user's org only)
- Show a stats grid with: total users, active this week, revenue this month
- Client-side date range filter (last 7d, 30d, 90d default)
- Loading skeleton while data loadsClaude generates the server component for data fetching, the client component for the interactive filter, and passes props across the server/client boundary correctly. It adds loading.tsx for the streaming UI and handles the Clerk auth check.
Server Actions for Forms
Add a form to the settings page that updates the user's display name.
Use a Server Action — no extra API route.
Validate with Zod, show inline errors, optimistic update while submitting.Claude writes the Server Action with validation, the form with useFormState/useFormStatus for optimistic UI, and error display. It correctly marks the form component as "use client" while keeping the action server-side.
Dynamic Routes with Static Generation
I have a blog at /blog/[slug]. Posts are in my CMS.
Generate static pages at build time but revalidate every hour.
Handle the 404 case for unknown slugs.Claude generates generateStaticParams for build-time generation, generateMetadata for SEO meta tags, notFound() for unknown slugs, and sets the correct revalidate value. It understands the difference between revalidate: 3600 (ISR) and revalidate: false (fully static).
Data Fetching Patterns
Parallel Data Fetching
Claude Code correctly uses Promise.all for parallel server-side fetches:
This page currently fetches user data, then their projects,
then their team members — three sequential awaits.
Parallelize all three.// Generated by Claude — correct parallel pattern
async function DashboardPage({ params }: { params: { orgId: string } }) {
const [user, projects, teamMembers] = await Promise.all([
getUser(params.orgId),
getProjects(params.orgId),
getTeamMembers(params.orgId),
]);
// ...
}It also knows when NOT to parallelize — if the second query depends on a result from the first, it keeps them sequential.
Streaming with Suspense
The dashboard is slow because of a heavy analytics query.
Keep the rest of the page fast and stream in the analytics section.Claude wraps the slow component in <Suspense> with a skeleton fallback, moves the data fetching into a separate async component, and explains why this works with Next.js streaming.
Caching Strategy
We fetch the same product catalog on multiple pages.
Cache it at the data layer for 5 minutes, shared across requests.Claude uses unstable_cache (Next.js 15) or React’s cache() correctly, sets appropriate tags for on-demand revalidation, and explains the tradeoff between cache duration and data freshness.
API Routes and Route Handlers
Create a webhook handler for Stripe at /api/webhooks/stripe.
Validate the signature, handle: checkout.session.completed,
customer.subscription.updated, customer.subscription.deleted.
Write to the database for each event type.Claude generates the Route Handler with:
- Raw body parsing (Stripe requires the raw buffer for sig validation)
- Stripe signature verification
- Event type switch with proper TypeScript narrowing
- Database writes for each event
- Proper 200/400 response codes
- No secrets exposed to client
This pattern comes up constantly in Next.js projects and Claude Code handles it reliably.
TypeScript with Next.js
Claude Code writes correct Next.js TypeScript — it doesn’t use any for params or searchParams:
// Claude generates properly typed page props
type PageProps = {
params: Promise<{ slug: string }>; // Next.js 15: params is a Promise
searchParams: Promise<{ page?: string }>; // searchParams too
};
export default async function BlogPost({ params, searchParams }: PageProps) {
const { slug } = await params;
const { page = '1' } = await searchParams;
// ...
}This matters because Next.js 15 changed params to be async — Claude Code knows this and doesn’t generate code that breaks silently on the latest Next.js.
For deeper TypeScript patterns, see the TypeScript guide.
Full-Stack Feature Development
The best workflow for adding a complete feature with Claude Code:
Example: Adding Team Invites
Add team invite functionality to the app.
Teams can invite users by email. Users get an email with an accept link.
Clicking accept adds them to the team.
Tech: existing Drizzle schema, Resend for email, Clerk for auth.
Requirements:
- POST /api/invites — create invite, send email
- GET /invite/[token] — accept page (shows team name before accepting)
- Server Action — accept invite, add to team, redirect to dashboard
- UI: Settings → Team → Invites section with pending listClaude generates the full feature: database schema changes (invite table with token, expiry, status), the API route, the email template via Resend, the accept page, the Server Action, and the settings UI — all connected correctly.
This is Claude Code’s strongest mode: give it a feature description with the tech constraints, and it generates everything. You review, test, and adjust rather than writing from scratch.
Debugging Next.js Issues
Hydration Errors
I'm getting a hydration error: "Text content does not match server-rendered HTML."
Here's the component: [paste]Claude diagnoses the common causes: server/client rendering mismatch (often from Date.now(), Math.random(), or browser-only APIs running on the server). It fixes the root cause rather than suppressing the error with suppressHydrationWarning.
Build Errors
My build is failing with: "You're importing a component that needs useContext.
It only works in a Client Component but none of its parents are marked with 'use client'."
Here are the components: [paste]Claude traces the component tree, identifies which component needs "use client", and adds it to the correct level — not just slapping it on the root component (which would undo the Server Component benefits).
Performance Issues
My /product/[slug] pages are generating slowly in production.
They're using generateStaticParams but page generation takes 90 seconds.
Here's the getProduct query: [paste]Claude examines the query, identifies N+1 problems or missing indexes, and suggests optimizations — usually either batching the queries or reducing what generateStaticParams generates at build time (with on-demand generation for the rest).
Testing Next.js with Claude Code
Claude Code writes proper Next.js tests using Vitest or Jest with appropriate mocking:
Write tests for the DashboardPage component.
It relies on server-side data fetching and Clerk auth.
Use Vitest with msw for API mocking.Claude generates tests that mock Clerk’s auth helpers, mock the database queries via vi.mock, and test the component in isolation. It doesn’t try to render the full Next.js server — it tests the component in a controlled environment.
See the testing guide for comprehensive coverage of test patterns.
The Claude Skills 360 Workflow
The Claude Skills 360 bundle includes Next.js-specific skills for patterns you use repeatedly:
- Route scaffolding: Create a new route with loading, error, and metadata in seconds
- Server Action patterns: Form handling with validation and optimistic UI
- API route templates: Pre-built patterns for auth callbacks, webhooks, file uploads
- Component library: Shadcn-compatible components with proper TypeScript
Combined with a well-written CLAUDE.md, these skills make Next.js development dramatically faster — you spend time on product decisions, not boilerplate.
Start with the free tier — 360 skills that cover common development patterns including several Next.js-specific ones. No credit card needed.
Getting More from Claude Code in Next.js
The developers who get the most from Claude Code in Next.js projects share a few patterns:
- Keep CLAUDE.md updated as your architecture evolves — if you switch auth providers or ORMs, update it
- Give Claude the full constraint — don’t just say “add a form,” say “add a form using Server Actions with Zod validation and optimistic UI”
- Use Claude Code for the hard parts — routing, auth patterns, caching strategy — and Copilot inline for standard boilerplate
- Review Server vs Client component decisions — Claude is good at this but the boundary is where bugs hide
For React patterns that aren’t Next.js-specific, see the React frontend guide. For the full beginner setup, the Claude Code tutorial covers installation and first use.