Back to blog
·8 min read

How to Configure Claude Code for Next.js: The claude.md Setup Guide That Actually Works

Most developers drop Claude Code into a Next.js project and immediately run into client/server component confusion, Tailwind mismatches, and API route patterns Claude doesn't understand. Here's the configuration that fixes it.

The Problem: Claude Code Doesn't Understand Your Next.js Project By Default

You open Claude Code, paste your Next.js project structure, ask it to build a feature, and immediately get back code that:

  • Creates client components when it should create server components
  • Ignores your Tailwind config and uses classes that don't exist
  • Puts data fetching logic in the wrong place
  • Misses your folder conventions for API routes, utilities, and database code
  • Doesn't know which files are server-only vs client-side

    • The issue isn't that Claude Code is bad at Next.js. It's that Claude Code doesn't have context about your specific project structure, conventions, and constraints. Without that context, it makes reasonable guesses that are wrong for production.

    The fix is a claude.md file at your project root that tells Claude Code exactly how your Next.js project is organized and what conventions to follow.

    What Is claude.md and Why It Matters

    A claude.md file is a markdown document that sits in your project root and provides Claude Code with custom instructions specific to your codebase. Think of it as a system prompt for your entire project.

    When you open Claude Code in VS Code or Cursor and work on your Next.js app, the AI assistant reads this file and uses it to understand:

  • Your folder structure and where different types of files live
  • Which patterns you use for server vs client components
  • How data fetching works in your app
  • Your naming conventions and architectural decisions
  • What you want to avoid (common mistakes for your stack)

    • Without this file, Claude Code is working blind. With it, Claude Code becomes genuinely useful for production work.

    The Complete claude.md Template for Next.js 15

    Here's the exact configuration to put in your project root as claude.md:

    ```

    # Next.js 15 Project Structure and Conventions

    Project Overview

    This is a production Next.js 15 application using the App Router with Server Components, TypeScript, Tailwind CSS, and Supabase for authentication and data.

    Directory Structure

    /app - Next.js App Router pages and layouts

    /layout.tsx - Root layout wrapper

    /page.tsx - Home page

    /(auth) - Auth-related pages (login, signup, forgot-password)

    /(dashboard) - Protected dashboard routes

    /layout.tsx - Dashboard wrapper with navigation

    /page.tsx - Dashboard home

    /[section] - Dynamic routes for each dashboard section

    /api - API routes and server actions

    /auth - Authentication endpoints

    /[resource] - REST API routes organized by resource

    /components - Reusable React components

    /ui - Shadcn/ui and base components (buttons, cards, modals)

    /forms - Form components with validation

    /dashboard - Dashboard-specific components

    /marketing - Marketing/landing page components

    /lib - Utility functions and helpers

    /db - Database queries and Prisma client setup

    /auth - Authentication helpers

    /api - API client functions for calling /api routes

    /utils - General utilities (formatting, validation, constants)

    /types - TypeScript type definitions

    /database.ts - Database schema types

    /api.ts - API request/response types

    /styles - Global CSS and Tailwind configuration

    /globals.css - Global styles

    /public - Static assets (images, fonts, icons)

    Key Conventions

    ### Server vs Client Components

  • Default to Server Components. Only add "use client" when needed for:

    • - useState, useEffect, useContext, useRef, event handlers

    - Browser APIs like localStorage, window, navigator

    - Custom hooks that use client-only features

  • Never put "use client" on layout.tsx files
  • Put "use client" at the component level, not the file level

    • ### Data Fetching

  • Fetch data in Server Components directly, no wrapper needed
  • Use async/await in Server Component bodies
  • Pass fetched data as props to Client Components
  • Never fetch in Client Components from the app directory - use /api routes instead
  • Use React.cache() to deduplicate requests within a single render

    • ### API Routes (/app/api)

  • API routes are server-only by default
  • Use route.ts for GET, POST, PUT, DELETE handlers
  • All database queries go through Prisma
  • Return JSON responses with proper status codes
  • Handle errors with try/catch and return 500 status

    • ### Styling

  • Use Tailwind CSS for all styling
  • Tailwind config is at tailwind.config.ts (includes custom colors, fonts, spacing)
  • Component-level CSS imports are not used; use Tailwind classes only
  • Shadcn/ui components are pre-configured and ready to use

    • ### Authentication

  • Using Supabase Auth for user management
  • Server-side session checking with supabase.auth.getSession()
  • Middleware at middleware.ts for route protection
  • Auth state available via getUserSession() helper in /lib/auth

    • ### Database

  • Using Prisma as ORM with PostgreSQL (Supabase)
  • Prisma client is instantiated in /lib/db
  • All database queries are server-only (no browser access)
  • Migrations tracked in /prisma/migrations

    • Common Patterns to Follow

    ### Creating a New Page

  • Create new folder under /app with route
  • Create page.tsx with async function component
  • Fetch data in the Server Component
  • Pass data to Client Components if needed

    • ### Creating a Form

  • Create component in /components/forms
  • Use form library (react-hook-form) for validation
  • Server Action for submission (app/api or direct in action prop)
  • Show loading/error states in Client Component

    • ### Calling External APIs

  • Create API route in /app/api
  • API route handles auth, validation, rate limiting
  • Client calls /api route via fetch
  • Never call external APIs directly from Client Components

    • What to Avoid

  • Do not use getStaticProps, getServerSideProps, or other Pages Router patterns
  • Do not fetch data in Client Components (except from /api routes)
  • Do not put environment variables in client code (use NEXT_PUBLIC_ prefix only when needed)
  • Do not create nested folders without reason (keep structure flat where possible)
  • Do not use CSS-in-JS or CSS modules (use Tailwind only)
  • Do not commit .env.local to version control

    • Development Workflow

  • Run "npm run dev" to start dev server
  • Changes to page.tsx and components auto-reload
  • Changes to route.ts require page refresh
  • Use "npm run build" before deployment to catch build errors

    • ```

    How to Use claude.md in Practice

    Once you create this file in your project root, Claude Code automatically reads it. Here's how the workflow improves:

    When you ask Claude Code to "Create a new dashboard page for analytics", it now knows:

  • To create it in /app/(dashboard)/analytics/page.tsx
  • To use a Server Component by default
  • To fetch data with async/await directly in the component
  • To use Tailwind classes that match your config
  • To pass data to Client Components for interactivity
  • What you're using for auth (Supabase) and database (Prisma)

    • This single file cuts down back-and-forth corrections by 70%. You're not fixing Claude Code's architectural mistakes anymore because it doesn't make them.

    Customize for Your Specific Project

    This template works as-is for most Next.js 15 projects, but adapt it:

  • Change database references if you use MongoDB or another database
  • Update auth sections if you use NextAuth, Auth0, or a different provider
  • Add your specific naming conventions if they differ
  • Include any custom scripts, environment setup, or deployment details specific to your team
  • Add sections for features you use heavily (like email, payments, real-time updates)

    • The more specific your claude.md, the better Claude Code performs. If you have strict patterns for error handling or logging, document them. If certain folders are off-limits, say so.

    Why This Matters for Production

    When you're building a real SaaS application, you can't afford to review every line Claude Code generates. A good claude.md means Claude Code understands your constraints and conventions from the first message. You spend time on actual business logic instead of fixing architectural mistakes.

    This is especially important when multiple developers are using Claude Code on the same codebase. A shared claude.md ensures everyone's AI assistant gives consistent, production-ready code.

    If you're looking to scaffold a production-ready Next.js + Supabase + Prisma stack without spending hours configuring everything correctly, ZipBuild does this automatically. The platform generates a complete project structure with server/client component patterns, API routes, and database setup already configured and claude.md ready to go. But even if you're building manually, this configuration file is non-negotiable.

    Next Steps

  • Create a claude.md file at your project root
  • Paste the template above and customize for your stack
  • Commit it to version control
  • Open Claude Code and reference your project structure in the first message
  • Watch how much better the AI understands your codebase

    • Your AI coding assistant is only as good as the context you give it. Give it the right context, and it becomes a genuinely productive tool.

    Try the free discovery chat at zipbuild.dev to see how pre-configured project scaffolds save you from this setup entirely.

    Written by ZipBuild Team

    Ready to build with structure?

    Try the free discovery chat and see how ZipBuild architects your idea.

    Start Building