How to Build a Next.js App with Claude Code

Building a Next.js app with Claude Code is fastest when the App Router architecture is established correctly from the start. The App Router introduced server components, async layouts, and interleaved client-server logic, and Claude Code handles these patterns well when given clear instructions.

Set up the project structure before opening Claude Code. With the right CLAUDE.md in place, Claude Code generates correct server and client component patterns throughout the build, from root layout to Vercel deployment.

Key Takeaways

• Use App Router for new projects: App Router is Next.js's current architecture and what Claude Code generates most reliably. Pages Router is legacy.
• CLAUDE.md prevents common mistakes: Without it, Claude Code mixes server and client component patterns; with it, the distinction applies consistently.
• Server components are the default: Components needing onClick, useState, or useEffect require "use client". Everything else stays as a server component.
• Claude Code excels at boilerplate: Route setup, layout files, loading and error boundaries, and metadata configuration are where it saves the most time.
• Data fetching is async by default: Server components can be async functions that await database or API calls directly. Claude Code generates this correctly.
• Vercel is the fastest path to production: Connect the GitHub repository, add environment variables, and deploy. No extra configuration needed.

AI App Development

Your Business. Powered by AI

We build AI-driven apps that don’t just solve problems—they transform how people experience your product.

Let's talk

App Router vs Pages Router: Which Should You Use?

Use App Router for all new Next.js projects. It is the current architecture, actively developed, and what Claude Code generates most confidently. Pages Router is maintained but receives no new innovation from the Next.js team.

App Router is the right choice. Its app/ directory structure, layout.tsx files, and server-first component model are exactly what Claude Code is trained to produce.

• App Router is actively developed: Next.js 13+ features, including server components and async layouts, only exist in the App Router architecture.
• Pages Router is still valid for existing projects: If you have a Pages Router codebase, specify "Pages Router" in CLAUDE.md so Claude Code does not mix patterns.
• The key mental model: Components are server components by default; only add "use client" when the component needs state, browser APIs, or event handlers.
• CLAUDE.md locks the architecture: Confirming App Router in CLAUDE.md prevents Claude Code from generating Pages Router patterns in the same project.
• Key App Router files Claude Code works with: app/layout.tsx, app/page.tsx, loading.tsx, error.tsx, and route.ts for API routes.

For a full stack app walkthrough with Claude Code showing App Router in a complete project with a database and API, that guide covers the stack end-to-end.

How Do You Set Up the Project and CLAUDE.md?

Run npx create-next-app@latest first, then write CLAUDE.md before giving Claude Code any tasks. This two-step sequence produces consistent, correctly structured output across the entire build.

Project structure must exist before Claude Code can work with it reliably. Create the app and the configuration file in sequence, not simultaneously.

• Run create-next-app with the right options: Select TypeScript, Tailwind CSS, App Router, and the src/ directory option when prompted during setup.
• Create CLAUDE.md immediately after setup: Write it before giving Claude Code any tasks. Include stack, component rules, file structure, and commands.
• State the server vs client rule explicitly: Write "Components are server components unless they use useState, useEffect, useRef, or browser event handlers. In those cases, add 'use client' at the top."
• Separate environment variable types: List NEXT_PUBLIC_ prefix variables (client-accessible) separately from server-only variables to prevent accidental secret exposure.
• Include your commands section: List npm run dev, npm run build, and npm run test so Claude Code runs the right commands without asking.

For the wider structural principles that keep Claude Code builds maintainable, structuring your project for Claude Code covers folder conventions and how CLAUDE.md shapes output.

How Do You Build the UI: Layouts, Pages, and Components?

Build from outside in: root layout first, then page layouts, then page content, then reusable components. Claude Code stays coherent when the UI structure builds out in layers rather than all at once.

Layer-by-layer building keeps Claude Code oriented. Starting with the root layout and working inward produces cleaner, more consistent output than building multiple pages simultaneously.

• Start with root layout: Ask Claude Code to create app/layout.tsx with HTML structure, Tailwind base classes, and a <nav> component before touching any page content.
• Generate pages with placeholder content first: For each route, create app/[route]/page.tsx with placeholder content, then fill in real content in a second pass.
• Extract components by name and props: When prompting for extraction into components/, specify the file name and props interface for cleaner TypeScript output.
• Tailwind patterns Claude Code handles well: Responsive breakpoint classes (sm:, md:, lg:), dark mode (dark:), and conditional class strings for component variants.
• Keep each task isolated: Ask for one layout or one page at a time. Context stays cleaner and Claude Code produces more consistent output.

For apps that include data visualisation or complex table and chart UI, building a data-heavy React dashboard covers component composition and chart library integration.

How Do You Handle Data Fetching and Server Components?

Server components in App Router can be async functions that await data calls directly. Prompt Claude Code with the data source and resource name and it generates this pattern correctly.

App Router removed the need for getServerSideProps and getStaticProps. Data fetching is now co-located with the component that needs it.

• Prompt for direct async server components: Use "fetch [resource] in a server component using [Supabase/Prisma/API URL]" and Claude Code generates the correct async component pattern.
• Use fetch() for external APIs: Reserve direct database client calls (Supabase, Prisma) for your own data. No API round-trip needed from server components.
• Specify your client-side fetching preference in CLAUDE.md: Choose between useState with useEffect, SWR, or TanStack Query and name it explicitly so Claude Code stays consistent.
• Generate error.tsx alongside async pages: Ask Claude Code to add these boundary files next to pages that do async data fetching so errors surface cleanly.
• Add loading.tsx for slow data fetches: App Router displays these automatically while the page awaits data. They are one prompt each and save visible loading state work.

For SaaS apps that need user-specific data fetching with auth context, building a Next.js SaaS MVP covers the complete auth-to-data-fetch pattern.

What Does Claude Code Handle Well in Next.js — and Where Does It Need Guidance?

Claude Code is strongest on boilerplate-heavy Next.js work: route setup, layout and page files, TypeScript interfaces, metadata configuration, and API routes. It needs explicit direction for state management, image optimisation, and middleware.

Knowing the difference between what Claude Code handles confidently and what needs careful review saves debugging time later in the build.

• Strong on App Router boilerplate: generateStaticParams, generateMetadata, revalidate export, and notFound() are all boilerplate-heavy patterns where Claude Code saves significant time.
• Needs explicit state management direction: Specify whether to use Zustand, Jotai, or Context in CLAUDE.md. Without this, Claude Code may use inconsistent patterns across the project.
• Review image optimisation settings: Claude Code generates <Image> component usage but may not set optimal sizes props for all viewport breakpoints.
• Verify middleware matcher patterns: Claude Code generates middleware.ts structure correctly, but complex routing matcher rules need manual verification.
• Watch for mixed router patterns: If CLAUDE.md does not specify App Router, Claude Code occasionally mixes App Router and Pages Router patterns in the same project.
• Third-party configs need verification: Library configurations that changed after Claude Code's training cutoff may be outdated. Check against current documentation.

How Do You Deploy the Next.js App to Vercel?

Push the project to GitHub, connect the repository to Vercel, add environment variables in the Vercel dashboard, and deploy. Next.js on Vercel requires no additional configuration beyond these steps.

Vercel is purpose-built for Next.js and handles the deployment complexity automatically. The main tasks are environment setup and a pre-deployment build check.

• Push to GitHub before connecting Vercel: Vercel deploys on every push to the connected branch. The repository must exist before the connection is made.
• Vercel auto-detects Next.js: Import the repository in Vercel's dashboard and the framework is identified automatically. Set the root directory only if Next.js is not at the repository root.
• Add environment variables in Vercel's dashboard: These are separate from .env.local which stays local and is never committed to the repository.
• Run npm run build locally first: Ask Claude Code to do this before the first Vercel deployment to catch TypeScript errors and missing environment variable references early.
• Use preview deployments for review: Vercel creates a preview URL for every pull request. Review Claude Code's changes in a live preview before merging to the main branch.

For setting up automated tests that run on every deployment, automated CI/CD pipeline with Claude Code covers GitHub Actions integration with Vercel deployment hooks.

Conclusion

Building a Next.js app with Claude Code is most productive when App Router is set up correctly from the start. Correct CLAUDE.md, correct component rules, and correct data fetching patterns are what make Claude Code consistent across a multi-session build.

The boilerplate-heavy parts of Next.js are exactly where Claude Code saves the most time, leaving you to focus on application logic. Create your project with create-next-app, write the CLAUDE.md with component rules and file structure conventions, and give Claude Code its first task: the root layout.

AI App Development

Your Business. Powered by AI

We build AI-driven apps that don’t just solve problems—they transform how people experience your product.

Let's talk

Want a Next.js App Built to Production Standards?

Building a Next.js app with App Router and deploying it correctly the first time requires more than the right prompts. Getting the server and client component split right, the data fetching patterns clean, and the Vercel deployment stable is a full-stack architecture problem, not just a coding task.

At LowCode Agency, we are a strategic product team, not a dev shop. We build Next.js applications with App Router, TypeScript, Supabase, and Vercel deployment using a structured process that produces production-ready output from the first sprint.

• Architecture scoping: We define App Router structure, server and client component boundaries, and data fetching patterns before writing a single line of code.
• CLAUDE.md configuration: We set up the project-level configuration so Claude Code generates consistent, correctly structured output throughout the build.
• Full-stack implementation: We build layouts, pages, components, API routes, and database integrations with clean TypeScript and Tailwind throughout.
• Data layer setup: We connect Supabase, Prisma, or your chosen database with correct server component data fetching patterns and error boundaries.
• Vercel deployment: We configure environment variables, preview deployments, and production build pipelines for a stable launch process.
• Testing and QA: We run build checks, type checks, and functional testing before every deployment so production stays stable.
• Ongoing development: We support feature additions and refactors using Claude Code and structured review so the codebase stays maintainable as it grows.

We have built 350+ products for clients including Coca-Cola, American Express, and Medtronic.

If you want a Next.js application built to production standards, Next.js development with LowCode Agency starts with a scoping call to define the right architecture for your product.