Vercel Next.js CLAUDE.md

# Next.js Development Guide

> **Note:** `CLAUDE.md` is a symlink to `AGENTS.md`. They are the same file.

## Codebase structure

### Monorepo Overview

This is a pnpm monorepo containing the Next.js framework and related packages.

```
next.js/
├── packages/           # Published npm packages
├── turbopack/          # Turbopack bundler (Rust) - git subtree
├── crates/             # Rust crates for Next.js SWC bindings
├── test/               # All test suites
├── examples/           # Example Next.js applications
├── docs/               # Documentation
└── scripts/            # Build and maintenance scripts
```

### Core Package: `packages/next`

The main Next.js framework lives in `packages/next/`. This is what gets published as the `next` npm package.

**Source code** is in `packages/next/src/`.

**Key entry points:**

- Dev server: `src/cli/next-dev.ts` -> `src/server/dev/next-dev-server.ts`
- Production server: `src/cli/next-start.ts` -> `src/server/next-server.ts`
- Build: `src/cli/next-build.ts` -> `src/build/index.ts`

## Build Commands

```bash
pnpm --filter=next build        # Build the Next.js package
pnpm build                      # Build all JS code
pnpm build-all                  # Build all JS and Rust code
```

## Fast Local Development

For iterative development, default to watch mode + skip-isolate for the inner loop.

```bash
pnpm --filter=next dev          # Auto-rebuilds on file changes (~1-2s per change vs ~60s full build)

NEXT_SKIP_ISOLATE=1 NEXT_TEST_MODE=<dev|start> pnpm testheadless test/path/to/test.ts
```

**For type errors only:** Use `pnpm --filter=next types` (~10s) instead of `pnpm --filter=next build` (~60s).

## Testing

```bash
pnpm test-dev-turbo test/path/to/test.test.ts    # Development mode with Turbopack (default)
pnpm test-dev-webpack                             # Development mode with Webpack
pnpm test-start-turbo                             # Production build+start with Turbopack
pnpm test-start-webpack                           # Production build+start with Webpack
pnpm test-unit                                    # Unit tests only (fast, no browser)
```

## Writing Tests

- **Use `pnpm new-test` to generate new test suites**
- **Use `retry()` from `next-test-utils` instead of `setTimeout` for waiting**
- **Do NOT use `check()` - it is deprecated. Use `retry()` + `expect()` instead**

## Key Directories (Quick Reference)

- `packages/next/src/` - Main Next.js source code
- `packages/next/src/server/` - Server runtime (most changes happen here)
- `packages/next/src/client/` - Client-side runtime
- `packages/next/src/build/` - Build tooling
- `test/e2e/` - End-to-end tests