The Next.js repository is a high-performance monorepo containing the core framework, its build systems (both Webpack and Rust-based Turbopack), and a vast ecosystem of supporting packages. It is designed to support both the legacy Pages Router and the modern App Router while maintaining a unified developer experience through its CLI and internal runtime abstractions.
Next.js uses a pnpm workspace managed with Lerna to orchestrate dozens of packages pnpm-lock.yaml1-20 lerna.json1-5 The architecture is increasingly hybrid, shifting heavy computation tasks (like transpilation and bundling) to Rust-based tooling while maintaining a flexible JavaScript/TypeScript core for framework logic. The repository also includes a patches/ directory to manage overrides for upstream dependencies pnpm-lock.yaml28-61
The packages/ directory contains the primary units of distribution. While next is the flagship package, many specialized features are split into standalone utilities.
| Package | Role | Key Code Entities |
|---|---|---|
next | Core framework runtime and build logic | BaseServer, renderToHTMLOrFlight, NextNodeServer |
@next/swc | Rust-based compiler transforms | next-custom-transforms, next-napi-bindings packages/next/package.json171 |
create-next-app | CLI for scaffolding new projects | index.ts packages/create-next-app/package.json18-19 |
@next/env | Environment variable loading | dotenv, dotenv-expand packages/next-env/package.json33-35 |
@next/font | Font optimization system | fontkit, google/, local/ packages/font/package.json12-26 |
@next/codemod | Automated migration scripts | jscodeshift transforms packages/next-codemod/package.json18 |
@next/third-parties | Optimized third-party loaders | google/index.ts packages/third-parties/package.json9-12 |
@next/eslint-plugin-next | ESLint plugin for Next.js specific rules | dist/index.js packages/eslint-plugin-next/package.json5-6 |
eslint-config-next | Recommended ESLint configurations | core-web-vitals, typescript packages/eslint-config-next/package.json50-57 |
@next/react-refresh-utils | Utilities for React Fast Refresh | dist/ packages/react-refresh-utils/package.json10 |
@next/polyfill-module | Polyfills for modern browsers | dist/polyfill-module.js packages/next-polyfill-module/package.json5 |
@next/polyfill-nomodule | Polyfills for older browsers | dist/polyfill-nomodule.js packages/next-polyfill-nomodule/package.json5 |
For a deep dive into every package and their inter-dependencies, see Monorepo Structure and Package Ecosystem.
The repository is organized around three primary execution phases: Build Time, Server Runtime, and Client Runtime.
Next.js supports two distinct build pipelines. The traditional pipeline is powered by Webpack, while the next-generation pipeline uses Turbopack, a Rust-based incremental bundler. Both rely on SWC for high-speed JavaScript/TypeScript transformations. The build process is orchestrated via taskr and native bindings packages/next/package.json84-102
The server runtime handles request routing and HTML/Flight (RSC) generation. It abstracts the underlying environment (Node.js or Edge) through common interfaces.
renderToHTMLOrFlight.getStaticProps/getServerSideProps data-fetching model.The client runtime manages hydration and subsequent transitions. The App Router client utilizes a specialized router-reducer to reconcile server-sent "Flight" data with the existing client-side component tree.
The following diagrams bridge the high-level system concepts to the specific entry points and classes found in the codebase.
Sources: packages/next/package.json80-101 packages/create-next-app/package.json17-19 packages/next-env/package.json18-19 packages/font/package.json9-14 packages/next-codemod/package.json37
Sources: packages/next/package.json103-109 packages/eslint-config-next/package.json15 packages/create-next-app/package.json2-3 packages/next-codemod/package.json2-3 packages/third-parties/package.json29 packages/font/package.json2 packages/next-polyfill-module/package.json2
Developers contributing to the monorepo must manage both a Node.js environment for the framework logic and a Rust toolchain for the native bindings. The repository uses pnpm for package management and taskr for internal build tasks packages/next/package.json84-102 pnpm-lock.yaml1-5
Key scripts for development include:
pnpm dev: Runs the development build using taskr packages/next/package.json84pnpm build: Runs the release build packages/next/package.json85For instructions on environment setup, local linking, and running the test suite, see Getting Started and Developer Setup.
turbo-tasks engine.renderToHTMLOrFlight logic and the AsyncLocalStorage based WorkStore.eslint-plugin-next packages/eslint-plugin-next/package.json1-27 next-codemod packages/next-codemod/package.json1-37 and the next-test-utils used for E2E testing.Sources:
Refresh this wiki