Start a Next.js Project with Claude Code
Scaffold, configure, build, test, and deploy a production-ready Next.js 16 App Router project using Claude Code as your development partner.
Claude Code is not a code generator you paste from. It is a development partner that reads your project, understands context, and keeps your conventions consistent from the first file to the last commit. This tutorial walks through a full Next.js workflow: scaffold with one prompt, configure a proper CLAUDE.md, build a real feature with data fetching, lock in TypeScript strict mode and tests, then ship to Vercel. By the end you will have a live project and a repeatable process for every Next.js project after this.
Scaffold with one prompt
One prompt creates the full project. Specify App Router, TypeScript strict mode, Tailwind CSS 4, and your preferred src layout. Claude handles the scaffolding, installs dependencies, and confirms the dev server starts.
claude "Create a Next.js 16 project called 'dashboard-app' with:
- App Router (not Pages Router)
- TypeScript in strict mode
- Tailwind CSS 4
- src/ directory layout
- ESLint and Prettier configured
- A basic home page at app/page.tsx that just says Hello
After creating it, run npm run dev to confirm it starts."Set up your CLAUDE.md
A project CLAUDE.md tells Claude your conventions so it applies them consistently across every file it touches. Cover build commands, naming conventions, component patterns, and import style. This is the single biggest leverage point for a clean codebase.
cat > CLAUDE.md << 'EOF'
# CLAUDE.md - dashboard-app
## Stack
Next.js 16 (App Router), TypeScript (strict), Tailwind CSS 4, Vercel
## Commands
npm run dev # Dev server with Turbopack
npm run build # Production build
npm run lint # ESLint
npm run test # Vitest (once added)
## File Naming
- Components: PascalCase files, e.g. UserCard.tsx
- Utilities: camelCase files, e.g. formatDate.ts
- Route segments: lowercase with hyphens, e.g. app/user-settings/page.tsx
## Component Patterns
- Prefer Server Components by default
- Add 'use client' only when you need interactivity or browser APIs
- Props interface named [ComponentName]Props, defined above the component
- No default exports for shared components (named exports only)
- No React.FC type annotation
## Import Style
- Absolute imports via @/ alias (configured in tsconfig)
- Group: 1) React/Next, 2) third-party, 3) internal (@/), 4) relative
- No barrel files (index.ts re-exports): import directly from the source file
## TypeScript Rules
- No any. Use unknown and narrow with type guards.
- Infer simple local variable types. Add explicit types on all exported functions.
- Use interface for object shapes, type for unions and mapped types.
## Styling
- Tailwind utility classes only. No CSS modules, no inline styles.
- Class variants via clsx or cn helper.
- Dark mode via dark: prefix (class strategy).
## What NOT to do
- Do not use Pages Router patterns (getServerSideProps, _app.tsx, etc.)
- Do not add console.log to production code
- Do not create new dependencies without flagging it first
EOFBuild your first feature
Build a dashboard page that fetches data server-side. This covers the core App Router pattern: async Server Component, loading state with Suspense, and a reusable card component with typed props.
claude "Build a dashboard page at app/dashboard/page.tsx that:
1. Is an async Server Component (no 'use client')
2. Fetches user stats from a mock async function in lib/data.ts
3. Displays the stats in a grid of StatCard components
4. Has a Suspense boundary with a loading skeleton
5. Uses named exports for all components
6. Types everything properly with TypeScript interfaces"Add tests and types
Claude writes Vitest tests for the components and utility functions, verifies TypeScript strict mode passes with zero errors, and flags any type gaps it finds. No untested code ships.
claude "Add tests to this project:
1. Install Vitest and @testing-library/react
2. Write unit tests for getUserStats() in lib/data.test.ts
3. Write component tests for StatCard in StatCard.test.tsx
4. Run the tests and fix any failures
5. Then run: npx tsc --noEmit and fix any TypeScript errors"Deploy to Vercel
One command ships the project live. Vercel detects Next.js automatically, builds with the right settings, and gives you a production URL. No configuration file needed for a standard Next.js 16 App Router project.
# Commit your work first
git add -A && git commit -m "feat: initial dashboard with tests"
# Deploy to production
vercel --prodShare what you built
Let your network know. Pre-filled post (edit before posting).
Just completed "Start a Next.js Project with Claude Code" on Claude Code Guide in 20 min. No coding experience needed. Claude does the work, you do the thinking. 👇 Free tutorial: https://claudecodeguide.dev/tutorials/nextjs-with-claude
What's next?
Debug and refactor with Claude Code