Architecture

Next.js is a layered system. The top-level CLI dispatches to one of three runtime roles — dev server, production server, or build — and each role drives a different set of subsystems through a shared core. The Rust pipeline and the Node.js pipeline meet in the bundler layer, where Turbopack (Rust) or webpack/rspack (JavaScript) takes over.

High-level diagram

graph TD
    CLI["CLI<br/>packages/next/src/cli/*"] --> Dev["next dev"]
    CLI --> Build["next build"]
    CLI --> Start["next start"]

    Dev --> DevServer["Dev server<br/>server/dev/next-dev-server.ts"]
    Start --> ProdServer["Prod server<br/>server/next-server.ts"]
    Build --> BuildPipeline["Build pipeline<br/>build/index.ts"]

    DevServer --> RouterServer["Router server<br/>server/lib/router-server.ts"]
    ProdServer --> RouterServer
    RouterServer --> BaseServer["Base server<br/>server/base-server.ts"]

    BaseServer --> AppRender["App Router rendering<br/>server/app-render/app-render.tsx"]
    BaseServer --> PagesRender["Pages Router rendering<br/>server/render.tsx"]
    BaseServer --> RouteHandler["Route handlers<br/>server/route-modules/*"]

    BuildPipeline --> WebpackBuild["webpack-build<br/>build/webpack-build/"]
    BuildPipeline --> TurbopackBuild["turbopack-build<br/>build/turbopack-build/"]

    DevServer --> HotReloader["Hot reloaders<br/>server/dev/hot-reloader-*.ts"]
    HotReloader --> Turbopack["Turbopack (Rust)<br/>turbopack/crates/"]
    HotReloader --> Webpack["webpack 5"]
    HotReloader --> Rspack["rspack"]

    TurbopackBuild --> NextApi["next-api crate<br/>crates/next-api/"]
    NextApi --> NextCore["next-core crate<br/>crates/next-core/"]
    NextCore --> Turbopack

The three CLI roles

The bin entry packages/next/dist/bin/next dispatches to a per-command file under packages/next/src/cli/:

Command	Entry CLI file	Drives
next dev	packages/next/src/cli/next-dev.ts	Dev server with hot reloading
next build	packages/next/src/cli/next-build.ts	Production compilation
next start	packages/next/src/cli/next-start.ts	Long-running prod server
next export	packages/next/src/cli/next-export.ts	Static export (deprecated alias)
next info	packages/next/src/cli/next-info.ts	Diagnostic info dump
next typegen	packages/next/src/cli/next-typegen.ts	Generates typed routes
next telemetry	packages/next/src/cli/next-telemetry.ts	Toggles anonymous telemetry
next test	packages/next/src/cli/next-test.ts	Wraps Playwright for app testing
next upgrade	packages/next/src/cli/next-upgrade.ts	Runs codemods via @next/codemod

next analyze and next post-build are post-processing helpers that run after a build completes.

Request lifecycle

A request to a Next.js application hits a layered server stack before any user code runs.

sequenceDiagram
    participant Client
    participant RouterServer as router-server.ts
    participant Filter as filterInternalHeaders
    participant BaseServer as base-server.ts
    participant Match as Route matcher
    participant Render as Renderer

    Client->>RouterServer: HTTP request
    RouterServer->>Filter: strip __next* internal headers
    Filter->>BaseServer: forward sanitized request
    BaseServer->>Match: resolve route<br/>(app | pages | api | static)
    Match-->>BaseServer: RouteMatch
    BaseServer->>Render: render(req, match)
    Render-->>BaseServer: RenderResult (stream)
    BaseServer-->>Client: HTTP response (streamed)

The header filter in packages/next/src/server/lib/server-ipc/utils.ts strips internal x-next* headers so an external client cannot forge them. Route resolution goes through the matcher managers in packages/next/src/server/route-matcher-managers/ which consult one of the route-matcher providers under packages/next/src/server/route-matcher-providers/.

App Router rendering

The App Router uses React Server Components. The render function in packages/next/src/server/app-render/app-render.tsx (~7,000 lines) builds a Flight payload for each request.

graph LR
    Req[Request] --> WorkStore[Work async storage<br/>work-async-storage.external.ts]
    WorkStore --> ComponentTree[Build component tree<br/>create-component-tree.tsx]
    ComponentTree --> RSCStream[RSC stream<br/>react-server-dom-webpack/turbopack]
    RSCStream --> SSR[SSR pipe<br/>renderToReadableStream]
    SSR --> Postpone{PPR enabled?}
    Postpone -- yes --> Postponed[Postponed state<br/>postponed-state.ts]
    Postpone -- no --> Done[RenderResult]
    Postponed --> Done

The entry-base.ts boundary at packages/next/src/server/app-render/entry-base.ts is the single allowed point for react-server-dom-webpack/* imports. All other code goes through helpers exported from this file.

Build pipeline

packages/next/src/build/index.ts is the orchestrator. It performs:

1. Discovery (build/route-discovery.ts, build/validate-app-paths.ts) — walk the app/ and pages/ directories, collect routes, validate their shape.
2. Compilation — webpack (build/webpack-build/), turbopack (build/turbopack-build/), or rspack via packages/next-rspack.
3. Static analysis (build/analysis/, build/swc/) — read page exports and segment configs to decide rendering mode.
4. Static generation (build/static-paths/) — pre-render pages whose paths are known at build time.
5. Manifest generation (build/manifests/, build/generate-routes-manifest.ts) — write .next/routes-manifest.json, .next/build-manifest.json, and friends for the runtime to read.
6. Build trace (build/collect-build-traces.ts) — produce nft.json files that list which dependencies each route ships, used by hosting platforms.

Bundler integration

Three bundlers are supported. Turbopack is the default; webpack and rspack are alternates.

graph TD
    Build[next build] --> Bundler{Bundler}
    Bundler -- default --> Turbopack[Turbopack<br/>build/turbopack-build]
    Bundler -- --webpack --> Webpack[webpack 5<br/>build/webpack-build]
    Bundler -- NEXT_RSPACK=1 --> Rspack[rspack<br/>packages/next-rspack]

    Turbopack --> NextApi[crates/next-api]
    NextApi --> NextCore[crates/next-core]
    NextCore --> TpCore[turbopack/crates/turbopack-core]

    Webpack --> WebpackConfig[build/webpack-config.ts<br/>~3,000 lines]
    Rspack --> WebpackConfig

The dev server has a parallel set of hot-reloader implementations (one per bundler) under packages/next/src/server/dev/:

• hot-reloader-turbopack.ts — drives the Turbopack project subscription
• hot-reloader-webpack.ts — runs webpack in watch mode + hot middleware
• hot-reloader-rspack.ts — same as webpack but using rspack

Rust pipeline (next ↔ Turbopack)

The Rust crates under crates/ are the bridge between Next.js and Turbopack:

Crate	Role
crates/next-api	Public API consumed via napi/wasm: build a project, request entries, get manifests
crates/next-core	Translates Next.js config into Turbopack module options and resolution rules
crates/next-build	Orchestrates a full build run
crates/next-custom-transforms	SWC visitors for next/font, server actions, dynamic IO, etc.
crates/next-napi-bindings	napi-rs glue for Node.js consumers
crates/wasm	wasm-bindgen wrapper for browser/edge consumers

These call into the Turbopack subtree (turbopack/crates/), which is structured around the turbo-tasks incremental computation framework.

Two cooperating runtimes

Pages and route handlers can run in two runtimes:

• Node.js runtime — full Node API surface. Default for everything.
• Edge runtime — a sandboxed subset based on Web Standards. Implemented in packages/next/src/server/web/. Uses the @edge-runtime/vm package to execute user code with a restricted global object.

The edge runtime is what Vercel's edge network and Cloudflare Workers run against. The Node.js runtime is what next start and self-hosted deployments run.

Key source files

File	Purpose
packages/next/src/server/base-server.ts	Shared server logic for Node and Edge
packages/next/src/server/next-server.ts	Node.js production server
packages/next/src/server/dev/next-dev-server.ts	Dev server with HMR and on-demand compilation
packages/next/src/server/lib/router-server.ts	First request entry point; runs middleware and matching
packages/next/src/server/app-render/app-render.tsx	The App Router renderer (~7,000 lines)
packages/next/src/server/render.tsx	The Pages Router renderer
packages/next/src/build/index.ts	Build pipeline orchestrator (~3,500 lines)
packages/next/src/build/webpack-config.ts	webpack configuration generator
crates/next-api/src/lib.rs	Rust public API entry
turbopack/crates/turbo-tasks/src/lib.rs	Incremental computation framework