Claude Code × Next.js: Automate Your Project Setup Completely

Claude Code can scaffold a complete Next.js 16 project — TypeScript strict mode, Tailwind CSS v4, shadcn/ui, ESLint, pre-commit hooks, and Vercel deployment — in under 10 minutes. The key is writing a precise CLAUDE.md that defines your stack and rules upfront.

Ask Claude Code to "create a Next.js project," and what you get back has TypeScript configured so loosely it spits out type errors everywhere. This guide covers exactly what to put in CLAUDE.md to get the output you actually want. From CLAUDE.md structure to create-next-app automation, custom slash commands, pre-commit hooks, and Vercel deployment — all within a single session.

What Changes When You Let Claude Code Handle Next.js Setup?

If you were to list everything involved in bootstrapping a Next.js project by hand, it looks something like this:

• Running create-next-app and answering all the prompts
• Enabling TypeScript strict mode
• Installing and configuring Tailwind CSS v4
• Initializing shadcn/ui
• Setting up ESLint and Prettier
• Cleaning up .gitignore
• Organizing the src/ directory structure

Done manually, that's 30 to 60 minutes of work. With Claude Code, it takes 5 to 10.

The caveat: Claude Code only does what you tell it to do. "Make it good" or "use best practices" doesn't translate. You need to spell out exactly what configuration you want before handing anything off. That's what CLAUDE.md is for.

What's the Minimum CLAUDE.md You Need to Write?

The CLAUDE.md file at your project root is the design document Claude Code uses to understand your project. Here's a minimal but effective structure:

# Project Name

## Tech Stack
- Next.js 16+ (App Router)
- TypeScript (strict: true)
- Tailwind CSS v4
- shadcn/ui
- ESLint + Prettier

## Directory Structure
- `src/app/` — App Router routes
- `src/components/` — UI components
- `src/lib/` — Utility functions
- `src/types/` — Type definitions

## Coding Rules
- All components must be written in TypeScript
- No `any` types allowed
- Prefer `type` over `interface`
- Default to Server Components; only add `"use client"` when necessary

## Off-Limits
- No code outside `src/`
- No CSS-in-JS (use Tailwind)
- No `console.log` in committed code

Even this much dramatically improves code quality. The "Off-Limits" section is especially important — without explicit prohibitions, Claude Code will default to looser settings.

How Do You Run the Full Setup from create-next-app to shadcn/ui?

With CLAUDE.md ready, give Claude Code a prompt like this:

Create a new Next.js project.
- Project name: my-app
- Follow the tech stack defined in CLAUDE.md
- Run create-next-app and complete initialization through shadcn/ui setup

Claude Code will run something along these lines:

npx create-next-app@latest my-app \
  --typescript \
  --tailwind \
  --eslint \
  --app \
  --src-dir \
  --import-alias "@/*"

In Next.js 16, TypeScript, Tailwind CSS, ESLint, App Router, and Turbopack are all enabled by default. The flags above are still valid and make your intent explicit — important when you want Claude Code to produce deterministic output. Running create-next-app interactively can cause Claude Code to get stuck waiting for input, so always use flags.

After setup, tighten the TypeScript configuration:

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true
  }
}

How Do You Automate shadcn/ui, Tailwind v4, and ESLint Configuration?

Initializing shadcn/ui

npx shadcn@latest init

When instructing Claude Code, specify your style preferences in CLAUDE.md upfront:

## shadcn/ui Configuration
- style: default
- base color: slate
- CSS variables: enabled

Tailwind CSS v4 Configuration

v4 works differently from v3. Instead of tailwind.config.ts, configuration lives directly in your CSS file.

/* src/app/globals.css */
@import "tailwindcss";

@theme {
  --color-primary: oklch(0.5 0.2 250);
  --font-sans: "Inter", sans-serif;
}

Without an explicit note in CLAUDE.md, Claude Code will often generate v3-style config files. Add a clear instruction:

## Tailwind CSS
- Version: v4
- Configuration goes in globals.css under @theme
- Do not create tailwind.config.ts

ESLint Configuration

// eslint.config.mjs
import { dirname } from "path";
import { fileURLToPath } from "url";
import { FlatCompat } from "@eslint/eslintrc";

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

const compat = new FlatCompat({ baseDirectory: __dirname });

export default [
  ...compat.extends("next/core-web-vitals", "next/typescript"),
  {
    rules: {
      "@typescript-eslint/no-explicit-any": "error",
      "@typescript-eslint/no-unused-vars": "error",
    },
  },
];

How Do You Eliminate Repetitive Work with Custom Slash Commands?

Claude Code supports custom slash commands. Just drop a markdown file in .claude/commands/ and it becomes available immediately.

Component Generation Command

<!-- .claude/commands/component.md -->
# Generate Component

Create a component named $ARGUMENTS following these rules:
- File: `src/components/$ARGUMENTS.tsx`
- Write in TypeScript
- Match shadcn/ui styling conventions
- Include a Props type definition
- Also generate a Storybook story file (.stories.tsx)

To use it, type /component Button in the Claude Code chat. Done.

Page Generation Command

<!-- .claude/commands/page.md -->
# Generate Page

Create a page for $ARGUMENTS following App Router conventions:
- Create `src/app/$ARGUMENTS/page.tsx`
- Implement as a Server Component
- Include metadata export
- Also generate loading.tsx

Turn your most-used patterns into commands and stop rewriting the same instructions every session.

How Do You Automate pre-commit Hooks and Code Formatting?

Keep code quality consistent by running automated checks before every commit.

Husky + lint-staged Setup

npm install -D husky lint-staged
npx husky init

Configure .husky/pre-commit:

#!/usr/bin/env sh
npx lint-staged

Add lint-staged configuration to package.json:

{
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{css,md,json}": [
      "prettier --write"
    ]
  }
}

To have Claude Code set this up, add to CLAUDE.md:

## Automation
- pre-commit: run ESLint and Prettier via husky + lint-staged
- Also check for TypeScript build errors in pre-commit

Prettier Configuration

// .prettierrc
{
  "semi": false,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 100
}

How Do You Complete Vercel Deployment in a Single Session?

Once setup is done, you can have Claude Code handle the Vercel deployment too.

Start by installing the Vercel CLI:

npm install -g vercel

Then give Claude Code this instruction:

Deploy the current project to Vercel.
- Project name: my-app
- Framework: Next.js
- Use default build settings
- Pull environment variables from .env.local

The deployment command is straightforward:

vercel --prod

If you have environment variables, add them via dashboard or CLI:

vercel env add NEXT_PUBLIC_API_URL production

Link the GitHub repository and every push to main will trigger an automatic deployment from then on.

What Are the Common Failure Patterns and How Do You Avoid Them?

CLAUDE.md Isn't Being Loaded

CLAUDE.md in the project root is loaded automatically when Claude Code starts. However, if you launch Claude Code from a subdirectory, it may not be picked up. Always start claude from the project root.

Vague Instructions Produce Off-Target Code

Phrases like "make it nice" or "follow best practices" don't translate into consistent behavior. Write specific instructions: "implement as a Server Component in TypeScript strict mode, no any types."

Context Fades in Long Sessions

In longer sessions, Claude Code can appear to "forget" rules established early on. Check whether CLAUDE.md rules are still being followed, and if you notice drift, explicitly say: "Please revise this to follow the rules in CLAUDE.md."

Existing Files Getting Overwritten

Claude Code edits files proactively. If there are files you don't want touched, say so explicitly in CLAUDE.md:

## Do Not Edit
- `src/styles/design-tokens.css` — design token definitions (do not modify)
- `.env.local` — environment variables (read-only reference)

Related Articles

• Claude Code × Docker Dev Environment Setup — Building Next.js projects on Docker
• TypeScript Type-Safe Code Generation with Claude Code — Type-safe Next.js component generation patterns
• Claude Code Test Generation Practical Guide — Test automation after project setup
• Claude Code Context Management: CLAUDE.md Design Patterns — Advanced CLAUDE.md structuring techniques
• Claude Code × Prisma: Auto-Generate APIs from Your Schema — Full-stack automation after scaffolding
• Claude Code Commands Cheatsheet — Complete reference for built-in and custom commands
• Common Next.js App Router Mistakes with Claude Code — Avoid pitfalls after your project is set up

FAQ

Does Claude Code support Next.js 16 with Turbopack out of the box?

Yes. Next.js 16 enables Turbopack by default for both development and production builds. When Claude Code runs create-next-app@latest, the generated project automatically uses Turbopack — no extra flags needed.

Can I use an existing CLAUDE.md template across multiple projects?

Absolutely. Keep a base CLAUDE.md template with your preferred tech stack, coding rules, and directory structure. Copy it into each new project and tweak the project-specific sections. This is the fastest way to get consistent output from Claude Code across repositories.

What if Claude Code generates Tailwind v3 config instead of v4?

This happens when CLAUDE.md doesn't explicitly state the Tailwind version. Add a clear instruction: "Tailwind CSS v4 — configuration in globals.css under @theme, do not create tailwind.config.ts." Claude Code follows explicit rules over its training defaults. Check the Tailwind CSS v4 migration guide for the full list of v3 → v4 differences.

How do I prevent Claude Code from overwriting files I want to keep?

Add a "Do Not Edit" section to your CLAUDE.md listing protected files and directories. Claude Code respects these boundaries as long as they're stated explicitly. For extra safety, you can also use a .claudeignore file to exclude files from Claude Code's context entirely.

Is it safe to let Claude Code run vercel --prod directly?

Claude Code will ask for permission before executing shell commands that modify external state. You can review the command before approving it. That said, for production deployments, many teams prefer connecting their GitHub repository to Vercel and letting pushes to main trigger deployments automatically — this keeps your deployment history traceable and avoids accidental deploys.

Wrapping Up

Three things make the difference when automating Next.js setup with Claude Code:

1. Communicate intent precisely through CLAUDE.md: Define your tech stack, directory structure, and hard rules
2. Eliminate repetitive work with custom commands: Turn common patterns into reusable slash commands
3. Enforce quality with pre-commit hooks: Automate the mechanical checks before code review

The 30 minutes you invest in writing a solid CLAUDE.md pays off in every session that follows. Save it as a template and tweak it per project — that's the workflow that actually scales.