Claude Code for React — Next.js, Tailwind & Component Workflows

Claude Code is highly effective for React development when configured with your stack details. This guide covers CLAUDE.md templates for Next.js App Router, Tailwind CSS component generation, Vitest automation hooks, state management patterns, and the workflow prompts that consistently produce production-quality React code.

React / Next.js CLAUDE.md Template

Next.js App Router (modern stack)

# Project: [App Name]

## Stack
- Next.js 15, App Router (NOT Pages Router)
- React 19
- TypeScript 5 (strict mode)
- Tailwind CSS v4 + shadcn/ui components
- Package manager: pnpm

## Commands
```bash
pnpm dev          # start dev server (localhost:3000)
pnpm build        # production build
pnpm type-check   # tsc --noEmit
pnpm test         # vitest run
pnpm test:watch   # vitest watch mode
pnpm lint         # next lint
```

## App Router conventions
- Server Components by default (no 'use client' unless needed)
- 'use client' only for: event handlers, browser APIs, useState/useEffect
- Server Actions in app/actions/ directory
- Route handlers in app/api/[route]/route.ts
- Layouts: app/layout.tsx (root), nested for sections

## Component conventions
- Components in src/components/ (shared) or co-located in app/ (page-specific)
- shadcn/ui for base components: import from '@/components/ui/[name]'
- Custom components: PascalCase, one component per file
- Props interfaces above the component definition

## State
- Client state: Zustand stores in src/stores/
- Server state: TanStack Query (useQuery, useMutation)
- Forms: React Hook Form + Zod validation

## Styling
- Tailwind utility classes only (no inline styles, no CSS modules)
- Dark mode: class strategy (dark: prefix)
- Responsive: mobile-first (sm:, md:, lg:, xl:)

Vite + React (SPA)

# Project: [App Name]

## Stack
- React 18, Vite 5
- TypeScript 5, strict mode
- Tailwind CSS v3
- React Router v6 (SPA routing)
- Vitest + React Testing Library

## Commands
```bash
pnpm dev       # start vite dev server
pnpm build     # build dist/
pnpm test      # vitest run
pnpm preview   # preview production build
```

Automated Test Hooks

// .claude/settings.json
{
  "allowedTools": ["Edit", "Write", "Bash", "Read", "Glob", "Grep"],
  "hooks": [
    {
      "event": "PostToolUse",
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "cd $PROJECT_ROOT && pnpm vitest run --reporter=verbose 2>&1 | tail -30"
      }]
    }
  ]
}

TypeScript check hook

{
  "event": "PostToolUse",
  "matcher": "Write",
  "hooks": [{
    "type": "command",
    "command": "cd $PROJECT_ROOT && pnpm tsc --noEmit 2>&1 | head -20"
  }]
}

Component Generation Patterns

Generating new components

claude "create a DataTable component at src/components/DataTable.tsx.
Props: columns (ColumnDef[]), data (T[]), isLoading, onRowClick.
Use TanStack Table v8 for table logic.
Tailwind for styling. shadcn/ui Skeleton for loading state.
Add a Vitest test for the loading and empty states."

Building a complete page section

claude "build the /dashboard/analytics page.
Fetch data using TanStack Query from /api/analytics.
Show: total revenue (stat card), revenue over time (recharts LineChart),
top products (DataTable, reuse existing component).
All components server-rendered where possible; only chart is client.
Mobile responsive."

Form with validation

claude "create a CreateProjectForm component.
Fields: name (required, 3-50 chars), description (optional, max 500),
visibility (radio: public/private), tags (multi-select, max 5).
Use React Hook Form + Zod schema.
Submit via Server Action. Show error messages per field.
Test: renders, validation errors, submission."

Next.js App Router Patterns

State Management Workflows

Zustand store

claude "create a useCartStore Zustand store in src/stores/cart.ts.
State: items (CartItem[]), total (number).
Actions: addItem, removeItem, updateQuantity, clearCart.
Persist to localStorage using zustand/middleware persist.
Write unit tests for all actions."

TanStack Query data fetching

claude "add useProjects and useCreateProject hooks in src/hooks/useProjects.ts.
useProjects: GET /api/projects, cache for 5 minutes.
useCreateProject: POST /api/projects, invalidate useProjects on success.
Both typed with Project interface from src/types/project.ts."

Refactoring Workflows

Migrate Pages Router → App Router

claude "migrate pages/products/[id].tsx to App Router.
New location: app/products/[id]/page.tsx.
Convert getServerSideProps to async server component.
Convert getStaticPaths to generateStaticParams.
Keep component logic, update imports."

Extract reusable component

claude "the user avatar appears in 6 different components with duplicated code.
Extract to src/components/UserAvatar.tsx.
Props: user (User), size ('sm'|'md'|'lg'), showName.
Replace all 6 usages. Run pnpm type-check to verify."

5 Tips for React + Claude Code

1. Share a sample component in CLAUDE.md. A 30-line example teaches Claude your naming conventions, prop typing style, and className patterns better than 10 sentences of instruction.
2. Tell Claude your Next.js version (13, 14, 15) explicitly. App Router patterns evolved significantly between versions — the async component pattern and use() hook are 15-specific.
3. For Tailwind, add your tailwind.config.ts custom tokens to CLAUDE.md (brand colors, spacing scale). Claude will use text-brand-primary instead of hardcoding #4F46E5.
4. For complex UI flows, ask Claude to "add data-testid attributes to interactive elements" — this makes Playwright tests trivial and doesn't affect production rendering.
5. When adding a new feature spanning multiple files: describe the data shape first. "User type: {id, name, email, avatar, role: 'admin'|'user'}". Claude's component props, Zod schemas, and API types will all be consistent.