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

I asked Claude Code to "create a Next.js project," and what I got back had TypeScript configured so loosely it was spitting out type errors everywhere. This is a record of figuring out exactly what to put in CLAUDE.md to get the output I actually wanted.

"The AI generated sloppy code" is a problem that better instructions can fix. This article walks through everything from writing CLAUDE.md, to automated create-next-app scaffolding, custom commands, pre-commit hooks, and deploying to Vercel — 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
• 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 15+ (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 "@/*"

The key here is having Claude Code pass explicit flags to create-next-app. Running it interactively can cause Claude Code to get stuck waiting for input.

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
. "$(dirname -- "$0")/_/husky.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)

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.