Getting started

This page describes how to set up the Next.js monorepo for local development. If you are looking to use Next.js as a framework, see nextjs.org/docs — this wiki is about the framework's own source.

Prerequisites

Requirement	Version	Notes
Node.js	>=20.9.0	The repo pins v20 via .node-version
pnpm	10.33.0	Pinned via packageManager in package.json
Rust	nightly-2026-04-02	Set in rust-toolchain.toml; rustup will install on use
Cargo	bundled with Rust	crates/ and turbopack/crates/ are Cargo workspaces

A working cargo toolchain is required even for JavaScript-only changes because the postinstall step builds next-swc native bindings. The Rust toolchain is automatically pulled in via rust-toolchain.toml when you first run cargo.

Install

git clone https://github.com/vercel/next.js
cd next.js
pnpm install

The pnpm install step runs scripts/install-native.mjs which downloads or builds the next-swc native binary. If you are on a platform without prebuilt binaries (or doing development on swc transforms), see Building from source.

First build

After install, build everything once:

pnpm build-all

This is the recommended bootstrap for fresh clones and branch switches. It runs both the JavaScript build (pnpm build) and the native binary build via pnpm swc-build-native. Subsequent runs are deduplicated by Turborepo.

For day-to-day work after the first build, you can use:

Goal	Command	Time
Watch mode for packages/next	pnpm --filter=next dev	~1-2s/change
Type-check only	pnpm --filter=next types	~10s
Build only packages/next	pnpm --filter=next build	~60s
Full rebuild after branch switch	pnpm build-all	varies

Watch mode is the default agent rule when modifying source: keep pnpm --filter=next dev running in a separate terminal so each save triggers a fast incremental rebuild.

Build the Rust binary

To build next-swc from source:

pnpm swc-build-native

This invokes scripts/build-native.ts which delegates to cargo build --release -p next-napi-bindings. The output ends up in packages/next-swc/native/.

For wasm:

pnpm swc-build-wasm

If Turbopack starts producing unexpected errors after switching branches, the binary may be stale — delete packages/next-swc/native/*.node and run pnpm install to fetch the npm-published binary.

Run a sample app

The fastest way to validate your local Next.js is to point an existing app at it:

cd test/integration/basic
node ../../../packages/next/dist/bin/next dev

Or generate a toy fixture for a quick smoke test:

pnpm new-test -- --args true smoke-feature e2e
node packages/next/dist/bin/next dev test/e2e/smoke-feature
curl --max-time 10 http://localhost:3000

For local development against a real app, use pnpm next-with-deps (see scripts/next-with-deps.sh) which packs and links the local Next.js into the target project.

Run the test suite

# Fast unit tests (no browser)
pnpm test-unit

# Single integration test in dev mode with Turbopack
pnpm test-dev-turbo test/e2e/app-dir/app/index.test.ts

# Single integration test in production mode with webpack
pnpm test-start-webpack test/e2e/app-dir/app/index.test.ts

The pnpm testheadless shortcut runs without spawning the orchestration overhead — useful when iterating on the same test repeatedly. See Testing for the full matrix.

Lint and type-check

pnpm lint              # full lint: types, prettier, eslint, ast-grep, alex
pnpm lint-fix          # auto-fix where possible
pnpm types             # TypeScript only

The pre-commit hook (.husky/pre-commit) runs lint-staged with prettier and eslint on the changed files. Pre-validate matching the hook with:

pnpm prettier --with-node-modules --ignore-path .prettierignore --write <files>
npx eslint --config eslint.config.mjs --fix <files>

Repository layout cheat sheet

Path	What it is
packages/next/	The published next npm package
packages/	All other npm packages (eslint plugin, font, codemods)
crates/	Rust crates that wrap Turbopack for Next.js
turbopack/	Turbopack subtree (Rust crates)
test/	All test suites (e2e, integration, unit, development)
docs/	Source for nextjs.org/docs
examples/	200+ example Next.js apps
scripts/	Build, release, and maintenance scripts
bench/	Benchmarks for the framework
errors/	Error message documentation

Useful environment variables

Variable	Effect
NEXT_TELEMETRY_DISABLED=1	Disable telemetry while running locally
NEXT_PRIVATE_LOCAL_DEV=1	Mark pnpm next invocations as local-dev
NEXT_SKIP_ISOLATE=1	Skip packing Next.js per test (faster, but hides resolution bugs)
IS_WEBPACK_TEST=1	Force webpack in tests
IS_TURBOPACK_TEST=1	Force Turbopack in tests
NEXT_RSPACK=1	Use rspack instead of webpack
__NEXT_CACHE_COMPONENTS=true	Enable cache components (also enables PPR)
__NEXT_SHOW_IGNORE_LISTED=true	Disable internal-frame filtering in dev error stacks
DEBUG=next:*	Verbose debug logging

See Debugging for more.