Next.js is the framework Claude Code handles best among full-stack JavaScript options. If you are new to the tool, start with the what Claude Code is overview. The App Router patterns introduced in Next.js 13 and refined through 14 and beyond are well-represented in its training data, and the ecosystem tooling (Tailwind, shadcn/ui, Prisma, NextAuth) generates cleanly from well-formed prompts.
The workflow that produces maintainable Next.js apps is not starting with components. It is starting with routes and the data model underneath them. Everything else flows from those two decisions.
Next.js App Router has a mental model shift that many developers are still adjusting to: Server Components by default, Client Components opt-in. Claude Code understands this model, but only if your prompts reflect it. Specify “Server Component” or “Client Component” in your prompts, and the generated code will be architecturally correct.
Setting up a Next.js project with Claude Code
The right starting prompt
Do not ask Claude Code to “set up a Next.js project.” Give it the full context it needs to make good decisions. A strong starting prompt:
Scaffold a Next.js 14 App Router project with TypeScript, Tailwind CSS, and shadcn/ui. Use Prisma with PostgreSQL for the database. Include NextAuth.js for authentication. Create the following route groups: (auth) for login and register, (dashboard) for protected pages, and (marketing) for public pages. Here is the data model: [paste your model].
This prompt produces a coherent project structure. A vague prompt produces a generic scaffold you will immediately start fighting.
Define routes and data model before prompting
Spend time before your first Claude Code session mapping your application’s routes and the data entities they interact with.
Write this in a PLAN.md file, which works alongside your CLAUDE.md, the CLAUDE.md guide explains how to structure that file for session continuity. Include:
- Routes. Every route and whether it is public or protected.
- Data entity. The primary data entity each route reads or writes.
- User roles. The roles involved, if any.
- Key actions. What each page does.
This document is not Claude Code-specific. It is good software planning that makes Claude Code far more useful.
The recommended build workflow
Step 1: Scaffold and configure
Use your starting prompt to generate the project structure, install dependencies, and configure Tailwind and shadcn/ui. Review the generated tailwind.config.ts, next.config.ts, and tsconfig.json before proceeding.
Pay attention to the app folder structure. If it does not match your route plan, correct it now before any components are built.
Step 2: Generate the data model and Prisma schema
With the project structure confirmed, generate your Prisma schema from your data model plan. Ask Claude Code to include:
- All models with proper field types.
- Relations between models.
- Indexes on fields you will query frequently.
- An initial migration and seed script.
Review the generated schema.prisma carefully. Run prisma db push or prisma migrate dev and verify the schema creates the expected tables before building anything that touches the database.
Step 3: Build authentication
NextAuth.js with Prisma adapter is the most common pattern Claude Code will generate for Next.js auth. For a thorough treatment of auth patterns across different stacks, the guide on authentication implementation is worth reading alongside this section. Specify your providers (Credentials, Google, GitHub, or others) and ask for:
- The NextAuth configuration at
app/api/auth/[...nextauth]/route.ts. - Session type augmentation in
types/next-auth.d.ts. - Middleware at
middleware.tsprotecting your dashboard route group. - A login page and registration flow if using Credentials.
Test auth completely before moving to application features. A broken session layer creates confusing bugs across every subsequent component.
Step 4: Build Server Components for data display
Next.js App Router defaults to Server Components. Use them for any page that primarily displays data: dashboard overviews, list views, detail pages. A well-formed Server Component prompt:
Create a Server Component for /dashboard/projects that fetches all projects belonging to the current user from Prisma, sorted by updated date, and renders them as a card grid using shadcn/ui Card.
Claude Code generates clean async Server Components that fetch directly from Prisma without an intermediate API layer. This is the correct App Router pattern.
Step 5: Add Client Components for interactivity
Forms, modals, dropdowns, and anything with local state are Client Components. Mark them explicitly:
Create a Client Component for the project creation form. Use react-hook-form with zod validation. On submit, call the /api/projects POST route and redirect to the project page on success.
Keeping the boundary clear (Server Components for data, Client Components for interaction) produces more maintainable code than mixing them inconsistently.
Step 6: Build API routes for mutations
Use Next.js Route Handlers for data mutations (POST, PATCH, DELETE). Claude Code generates clean Route Handlers with auth verification, Zod request validation, Prisma calls, and typed responses.
Ask for one Route Handler file per resource. Review each for proper auth checks: every mutation handler should verify the session before touching the database.
Claude Code task review table
| Task | Claude Code handles well | Needs human review |
|---|---|---|
| Project scaffold and config | Strong | Verify tsconfig paths and next.config options |
| Prisma schema generation | Strong | Review indexes and relations before migrating |
| NextAuth configuration | Strong | Verify session strategy and provider config |
| Server Component data fetching | Strong | Check for N+1 queries in generated Prisma calls |
| Client Component forms | Strong | Review validation logic for business rules |
| Route Handler auth checks | Strong | Verify session check is present on every mutation |
| Middleware route protection | Strong | Test all protected and public route combinations |
| Loading and error UI | Good | Review error boundaries for user-friendly messaging |
| Image optimization | Partial | next/image used but dimensions often need adjustment |
| Performance optimization | Weak | Claude Code does not audit bundle size or Core Web Vitals |
| Deployment configuration | Good | Review env var handling before production deploy |
Common Next.js patterns Claude Code generates well
Server-side data fetching with caching
Claude Code correctly generates fetch calls with Next.js cache directives in Server Components and understands the revalidate and no-store options. Specify your caching requirements in the prompt.
Server Actions for form submission
Next.js Server Actions (the "use server" directive) allow form submissions to call server-side code directly without a Route Handler. Claude Code generates these cleanly for simple cases. Use them for straightforward mutations. Use Route Handlers for complex business logic.
Dynamic routes and generateStaticParams
Claude Code handles dynamic routes ([id], [slug]) and the generateStaticParams function for static generation correctly. Specify whether a dynamic route should be statically generated or dynamically rendered in your prompt.
Frequently asked questions
Should I use the App Router or Pages Router for a new Next.js project?
App Router for all new projects as of Next.js 14+. Claude Code understands App Router patterns well, and the ecosystem has largely standardized on it. Pages Router is supported for maintenance of existing projects.
How does Claude Code handle TypeScript in Next.js projects?
Well. Generated components, Route Handlers, and Prisma interactions are typed. The most common TypeScript issue in generated code is overly loose typing (excessive any or missing return type annotations on Route Handlers).
Review generated code for explicit return types on API routes.
What is the best way to handle environment variables with Claude Code?
Ask Claude Code to generate a .env.example file alongside any configuration that requires environment variables. Review it to ensure all required variables are listed. Never commit actual .env files.
Claude Code knows this and will not generate them with real values, but always verify before committing.
Can Claude Code handle Next.js internationalization (i18n)?
Claude Code understands Next.js i18n routing configuration and can scaffold the route structure for multi-locale apps. The actual translation management (message files, locale detection, translation keys) requires more careful prompting and manual review to ensure consistency.
Ready to build your Next.js app?
Next.js with Claude Code is one of the most productive full-stack development combinations available today. The framework’s conventions align with how Claude Code generates code, and the ecosystem tooling (Prisma, NextAuth, shadcn/ui, Tailwind) produces clean output from well-formed prompts. For a broader look at how this fits into a complete application, see how to build a full-stack app with Claude Code.
The developers shipping the fastest with Claude Code and Next.js are the ones who define their routes and data model before their first prompt, then build in layers: scaffold, schema, auth, Server Components, Client Components, mutations. Each layer is testable before the next begins.
Path one: do it yourself. Map your routes and data model in a PLAN.md file before your first session. Define your route groups, your primary data entities, and your auth requirements.
Start with the scaffold prompt, then generate the Prisma schema. You will have a working, authenticated app shell within a day.
Path two: work with Phos AI Labs. If you want a senior engineer to lead your Next.js build from architecture through deployment, Phos AI Labs runs structured development engagements. Thirty minutes, no deck. Start here.