---
title: "Project Structure"
description: "The repository follows a structured monorepo topology orchestrated via pnpm workspaces and Turborepo task pipelines, establishing clear boundaries between core packages, applications, benchmarks, a..."
last_updated: "2026-09-23T10:52:03.136804+00:00"
canonical_url: "https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/technical/getting-started/project-structure"
---

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [packages/next/package.json](https://github.com/blade47/next.js/blob/main/packages/next/package.json)
- [packages/next/taskfile.js](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js)
- [package.json](https://github.com/blade47/next.js/blob/main/package.json)
- [packages/next/types/$$compiled.internal.d.ts](https://github.com/blade47/next.js/blob/main/packages/next/types/%24%24compiled.internal.d.ts)
- [packages/next/constants.js](https://github.com/blade47/next.js/blob/main/packages/next/constants.js)
- [packages/next/types.js](https://github.com/blade47/next.js/blob/main/packages/next/types.js)
- [packages/next/src/bundles/webpack/packages/package.js](https://github.com/blade47/next.js/blob/main/packages/next/src/bundles/webpack/packages/package.js)
- [packages/next/turbo.json](https://github.com/blade47/next.js/blob/main/packages/next/turbo.json)
- [packages/next/document.js](https://github.com/blade47/next.js/blob/main/packages/next/document.js)
- [packages/next/app.js](https://github.com/blade47/next.js/blob/main/packages/next/app.js)
- [packages/next/constants.d.ts](https://github.com/blade47/next.js/blob/main/packages/next/constants.d.ts)
- [packages/next/src/bundles/webpack/packages/sources.js](https://github.com/blade47/next.js/blob/main/packages/next/src/bundles/webpack/packages/sources.js)
- [packages/next/src/api/server.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/api/server.ts)
- [packages/next/script.js](https://github.com/blade47/next.js/blob/main/packages/next/script.js)
- [packages/next/client.js](https://github.com/blade47/next.js/blob/main/packages/next/client.js)
- [packages/next/navigation.js](https://github.com/blade47/next.js/blob/main/packages/next/navigation.js)
- [packages/next/jest.js](https://github.com/blade47/next.js/blob/main/packages/next/jest.js)
- [packages/next-codemod/package.json](https://github.com/blade47/next.js/blob/main/packages/next-codemod/package.json)
- [packages/next/tsconfig.json](https://github.com/blade47/next.js/blob/main/packages/next/tsconfig.json)
- [packages/next/src/server/after/index.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/after/index.ts)
- [packages/next/index.d.ts](https://github.com/blade47/next.js/blob/main/packages/next/index.d.ts)
- [packages/next/src/next-devtools/entrypoint.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/next-devtools/entrypoint.ts)
- [packages/next/src/api/constants.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/api/constants.ts)
- [packages/next/tsconfig.build.json](https://github.com/blade47/next.js/blob/main/packages/next/tsconfig.build.json)
- [packages/next/src/api/navigation.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/api/navigation.ts)
- [packages/next/types.d.ts](https://github.com/blade47/next.js/blob/main/packages/next/types.d.ts)
- [pnpm-workspace.yaml](https://github.com/blade47/next.js/blob/main/pnpm-workspace.yaml)
- [turbo.json](https://github.com/blade47/next.js/blob/main/turbo.json)
</details>

## Overview

The repository follows a structured monorepo topology orchestrated via pnpm workspaces and Turborepo task pipelines, establishing clear boundaries between core packages, applications, benchmarks, and native build crates. Sources: [package.json:4-7](https://github.com/blade47/next.js/blob/main/package.json#L4-L7), [pnpm-workspace.yaml:1-8](https://github.com/blade47/next.js/blob/main/pnpm-workspace.yaml#L1-L8), [turbo.json:1-35](https://github.com/blade47/next.js/blob/main/turbo.json#L1-L35). Within the primary `next` package, functionality is organized into specialized internal subsystems, compiled vendor dependencies, and root-level module resolution facades that expose clean entry points for clients, servers, navigation, and testing while maintaining isolated compilation and build targets. Sources: [packages/next/package.json:5-82](https://github.com/blade47/next.js/blob/main/packages/next/package.json#L5-L82), [packages/next/taskfile.js:1450-1568](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L1450-L1568).

## Workspace and Monorepo Organization

### Overview

The repository's workspace topology is rooted at the top-level manifest and governed by `pnpm-workspace.yaml`, which outlines the exact package patterns included in the build graph. The included patterns encompass `apps/*`, `packages/*`, `bench/*`, `crates/*/js`, `turbopack/crates/*/js`, `turbopack/crates/turbopack-tests/tests/execution`, and `turbopack/packages/*`. Sources: [pnpm-workspace.yaml:1-8](https://github.com/blade47/next.js/blob/main/pnpm-workspace.yaml#L1-L8). Root package configurations also declare `workspaces` pointing to `"packages/*"`. Sources: [package.json:4-7](https://github.com/blade47/next.js/blob/main/package.json#L4-L7). Security and dependency hoisting are governed by `publicHoistPattern` containing `*eslint*`, allowed builds for `@ast-grep/cli`, and a `minimumReleaseAge` of `2880` minutes (48 hours) with specific exclusions for scopes such as `@next/*`, `@turbo/*`, `@vercel/*`, `@workflow/*`, `babel-plugin-react-compiler`, `next`, `react`, `react-dom`, `react-is`, `react-server-dom-*`, `scheduler`, and `turbo`. Sources: [pnpm-workspace.yaml:10-49](https://github.com/blade47/next.js/blob/main/pnpm-workspace.yaml#L10-L49).

### Turborepo Task Pipelines

Task orchestration is defined at the root via `turbo.json`, establishing global execution parameters, environment variables, and task dependency graphs. Global environment variables passed to tasks include `CI` and `NEXT_CI_RUNNER`, while `RUSTC_WRAPPER` and `SCCACHE_*` are passed through. Sources: [turbo.json:1-4](https://github.com/blade47/next.js/blob/main/turbo.json#L1-L4). The Turborepo configuration utilizes the terminal user interface (`"ui": "tui"`). Sources: [turbo.json:34](https://github.com/blade47/next.js/blob/main/turbo.json#L34).

| Task Name | Dependencies (`dependsOn`) | Inputs | Outputs / Environment | Purpose |
| :--- | :--- | :--- | :--- | :--- |
| `build` | `[^build]` | — | `dist/**` | Package compilation task referencing upstream workspace dependencies. Sources: [turbo.json:5-9](https://github.com/blade47/next.js/blob/main/turbo.json#L5-L9). |
| `dev` | `[^dev]` | — | `dist/**` | Development watch/serve task across workspace packages. Sources: [turbo.json:10-13](https://github.com/blade47/next.js/blob/main/turbo.json#L10-L13). |
| `storybook` | — | — | — | Storybook execution task. Sources: [turbo.json:14](https://github.com/blade47/next.js/blob/main/turbo.json#L14). |
| `build-storybook` | `[^build-storybook]` | — | `storybook-static/**` | Storybook compilation task. Sources: [turbo.json:15-18](https://github.com/blade47/next.js/blob/main/turbo.json#L15-L18). |
| `test-storybook` | `[^test-storybook]` | — | — | Storybook testing task. Sources: [turbo.json:19-21](https://github.com/blade47/next.js/blob/main/turbo.json#L19-L21). |
| `pack-for-isolated-tests` | — | `$TURBO_DEFAULT$, dist/**` | `packed.tgz` | Bundles package artifacts for isolated test runs. Sources: [turbo.json:22-25](https://github.com/blade47/next.js/blob/main/turbo.json#L22-L25). |
| `typescript` | — | — | — | Type checking task. Sources: [turbo.json:26](https://github.com/blade47/next.js/blob/main/turbo.json#L26). |
| `//#typescript` | — | — | — | Root-scoped type checking task. Sources: [turbo.json:27](https://github.com/blade47/next.js/blob/main/turbo.json#L27). |
| `//#get-test-timings` | — | `run-tests.js` | `test-timings.json` (Env: `KV_REST_API_URL`, `KV_REST_API_TOKEN`) | Fetches and records test timing metrics. Sources: [turbo.json:28-32](https://github.com/blade47/next.js/blob/main/turbo.json#L28-L32). |

Sources: [turbo.json:1-35](https://github.com/blade47/next.js/blob/main/turbo.json#L1-L35).

> [!NOTE]
> The sub-package `packages/next/turbo.json` extends the root workspace configuration (`"extends": ["//"]`) and overrides the `build` task to depend on both `@next/bundle-analyzer-ui#build` and `^build`, outputting to `dist/**`. Sources: [packages/next/turbo.json:1-10](https://github.com/blade47/next.js/blob/main/packages/next/turbo.json#L1-L10).

### Monorepo Scripts and Execution Workflow

Root scripts defined in `package.json` invoke Turborepo tasks, Lerna commands, and script runners to manage testing, linting, and building. For instance, package cleaning is executed via `lerna clean -y && lerna run clean && lerna exec 'node ../../scripts/rm.mjs dist'`. Sources: [package.json:11](https://github.com/blade47/next.js/blob/main/package.json#L11). Production builds run `turbo run build --remote-cache-timeout 60 --summarize true`, while extended builds execute `turbo run build build-native-auto --remote-cache-timeout 60 --summarize true`. Sources: [package.json:12-13](https://github.com/blade47/next.js/blob/main/package.json#L12-L13).

> [!IMPORTANT]
> When executing development environments or testing suites across multiple bundlers (such as Webpack, Rspack, and Turbopack), scripts leverage `scripts/run-jest.sh` with specific flags like `--mode=dev`, `--bundler=webpack`, and `--headless`. Sources: [package.json:22-29](https://github.com/blade47/next.js/blob/main/package.json#L22-L29).

Sources: [package.json:1-91](https://github.com/blade47/next.js/blob/main/package.json#L1-L91).

## Core Next Package Configuration

### Overview

The core `next` package configuration governs the structure, build mechanics, and type declarations of the Next.js framework package located in `packages/next`. It integrates package manifests (`package.json`), TypeScript compiler options (`tsconfig.json`, `tsconfig.build.json`), taskrunner integration via Taskr, and an extensive set of top-level type definition entry points (`index.d.ts`, `types.d.ts`). Sources: [packages/next/package.json:1-102](https://github.com/blade47/next.js/blob/main/packages/next/package.json#L1-L102), [packages/next/tsconfig.json:1-50](https://github.com/blade47/next.js/blob/main/packages/next/tsconfig.json#L1-L50), [packages/next/tsconfig.build.json:1-24](https://github.com/blade47/next.js/blob/main/packages/next/tsconfig.build.json#L1-L24), [packages/next/index.d.ts:1-20](https://github.com/blade47/next.js/blob/main/packages/next/index.d.ts#L1-L20).

### Package Manifest and Dependencies

The `packages/next/package.json` file establishes the identity of the package as `"name": "next"` with version `"16.3.0-canary.51"`, setting its main entry point to `./dist/server/next.js`, binary executable mapping for `next` under `./dist/bin/next`, and type declarations root pointing to `index.d.ts`. Sources: [packages/next/package.json:1-10, 80-82](https://github.com/blade47/next.js/blob/main/packages/next/package.json#L1-L10,_L80-L82).

Runtime dependencies and peer dependencies control compilation requirements and external framework compatibility.

| Dependency Type | Name / Identifier | Version / Range | Purpose |
| :--- | :--- | :--- | :--- |
| Dependency | `@next/env` | `16.3.0-canary.51` | Environment variable loading for Next.js. Sources: [packages/next/package.json:104](https://github.com/blade47/next.js/blob/main/packages/next/package.json#L104). |
| Dependency | `@swc/helpers` | `0.5.15` | SWC runtime helper functions. Sources: [packages/next/package.json:105](https://github.com/blade47/next.js/blob/main/packages/next/package.json#L105). |
| Dependency | `baseline-browser-mapping` | `^2.9.19` | Baseline browser mapping utility. Sources: [packages/next/package.json:106](https://github.com/blade47/next.js/blob/main/packages/next/package.json#L106). |
| Dependency | `caniuse-lite` | `^1.0.30001579` | Browser feature support database. Sources: [packages/next/package.json:107](https://github.com/blade47/next.js/blob/main/packages/next/package.json#L107). |
| Dependency | `postcss` | `8.5.10` | CSS transformations and styling pipelines. Sources: [packages/next/package.json:108](https://github.com/blade47/next.js/blob/main/packages/next/package.json#L108). |
| Dependency | `styled-jsx` | `5.1.6` | Component-scoped CSS styling. Sources: [packages/next/package.json:109](https://github.com/blade47/next.js/blob/main/packages/next/package.json#L109). |
| Peer Dependency | `@opentelemetry/api` | `^1.1.0` | Telemetry instrumentation tracing. Sources: [packages/next/package.json:112](https://github.com/blade47/next.js/blob/main/packages/next/package.json#L112). |
| Peer Dependency | `@playwright/test` | `^1.51.1` | End-to-end testing support. Sources: [packages/next/package.json:113](https://github.com/blade47/next.js/blob/main/packages/next/package.json#L113). |
| Peer Dependency | `babel-plugin-react-compiler` | `*` | React compiler optimization plugin. Sources: [packages/next/package.json:114](https://github.com/blade47/next.js/blob/main/packages/next/package.json#L114). |
| Peer Dependency | `react` | `^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0` | React core library peer requirement. Sources: [packages/next/package.json:115](https://github.com/blade47/next.js/blob/main/packages/next/package.json#L115). |
| Peer Dependency | `react-dom` | `^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0` | React DOM rendering peer requirement. Sources: [packages/next/package.json:116](https://github.com/blade47/next.js/blob/main/packages/next/package.json#L116). |
| Peer Dependency | `sass` | `^1.3.0` | Sass CSS preprocessor support. Sources: [packages/next/package.json:117](https://github.com/blade47/next.js/blob/main/packages/next/package.json#L117). |

Sources: [packages/next/package.json:103-118](https://github.com/blade47/next.js/blob/main/packages/next/package.json#L103-L118).

Package scripts configure local development (`dev`: `cross-env NEXT_SERVER_NO_MANGLE=1 taskr`), production compilation (`build`: `taskr release`), and type generation (`types`: `tsc --project tsconfig.build.json --declaration --emitDeclarationOnly --stripInternal --declarationDir dist`). Sources: [packages/next/package.json:83-87](https://github.com/blade47/next.js/blob/main/packages/next/package.json#L83-L87). The `taskr` property specifies taskfile requirements including `./taskfile-webpack.js`, `./taskfile-ncc.js`, `./taskfile-swc.js`, and `./taskfile-watch.js`. Sources: [packages/next/package.json:95-101](https://github.com/blade47/next.js/blob/main/packages/next/package.json#L95-L101).

Sources: [packages/next/package.json:83-102](https://github.com/blade47/next.js/blob/main/packages/next/package.json#L83-L102).

### TypeScript Configuration and Build Options

TypeScript options are structured across `tsconfig.json` extending `../../tsconfig-tsec.json` and `tsconfig.build.json` extending `tsconfig.json`. Sources: [packages/next/tsconfig.json:1-3](https://github.com/blade47/next.js/blob/main/packages/next/tsconfig.json#L1-L3), [packages/next/tsconfig.build.json:1-2](https://github.com/blade47/next.js/blob/main/packages/next/tsconfig.build.json#L1-L2). The compiler options enforce strictness and module bundling guidelines.

| Compiler Option | Value | Purpose |
| :--- | :--- | :--- |
| `strict` | `true` | Enables all strict type-checking options. Sources: [packages/next/tsconfig.json:4](https://github.com/blade47/next.js/blob/main/tsconfig.json#L4). |
| `stripInternal` | `true` | Omits declarations marked with `@internal` from emitted output. Sources: [packages/next/tsconfig.json:5](https://github.com/blade47/next.js/blob/main/tsconfig.json#L5). |
| `esModuleInterop` | `true` | Enables interoperability between CommonJS and ES Modules. Sources: [packages/next/tsconfig.json:6](https://github.com/blade47/next.js/blob/main/tsconfig.json#L6). |
| `verbatimModuleSyntax` | `true` | Preserves type-only imports and exports without transformation. Sources: [packages/next/tsconfig.json:7](https://github.com/blade47/next.js/blob/main/tsconfig.json#L7). |
| `jsx` | `react-jsx` | Emits JSX transformed with React 17+ fragment/element factories. Sources: [packages/next/tsconfig.json:8](https://github.com/blade47/next.js/blob/main/tsconfig.json#L8). |
| `module` | `ESNext` | Specifies ECMAScript module target generation. Sources: [packages/next/tsconfig.json:9](https://github.com/blade47/next.js/blob/main/tsconfig.json#L9). |
| `target` | `ES2018` | Sets JavaScript language target version. Sources: [packages/next/tsconfig.json:10](https://github.com/blade47/next.js/blob/main/tsconfig.json#L10). |
| `moduleResolution` | `bundler` | Resolves modules using bundler-style resolution rules. Sources: [packages/next/tsconfig.json:11](https://github.com/blade47/next.js/blob/main/tsconfig.json#L11). |
| `types` | `["trusted-types", "jest", "node"]` | Specifies global type packages included during compilation. Sources: [packages/next/tsconfig.json:12](https://github.com/blade47/next.js/blob/main/tsconfig.json#L12). |

Sources: [packages/next/tsconfig.json:4-12](https://github.com/blade47/next.js/blob/main/packages/next/tsconfig.json#L4-L12).

The configuration maps absolute paths to prevent circular overwriting errors during `tsc` execution and enables auto-completion before builds. Mapped paths include `next/dist/client/app-find-source-map-url`, `next/dist/client/app-call-server`, `next/dist/compiled/@edge-runtime/ponyfill`, `next/dist/compiled/@vercel/og/satori`, and `next/dist/shared/lib/image-loader`. Sources: [packages/next/tsconfig.json:13-34](https://github.com/blade47/next.js/blob/main/packages/next/tsconfig.json#L13-L34). 

> [!WARNING]
> `tsconfig.json` explicitly excludes output directories and legacy declaration files (`./dist/**/*`, `./*.d.ts`, `future/*.d.ts`, `image-types/global.d.ts`, `compat/*.d.ts`, `legacy/*.d.ts`, `types/compiled.d.ts`, `navigation-types/*.d.ts`, `navigation-types/compat/*.d.ts`, `experimental/**/*.d.ts`) to avoid input file overwrite conflicts. Sources: [packages/next/tsconfig.json:38-49](https://github.com/blade47/next.js/blob/main/tsconfig.json#L38-L49). Furthermore, `tsconfig.build.json` defines `"rootDir": "src"` and excludes test and storybook files (`./**/*.test.ts`, `./**/*.test.tsx`, `./**/*.stories.tsx`, `./**/storybook/**/*`) to prevent generating declarations for internal test code. Sources: [packages/next/tsconfig.build.json:1-24](https://github.com/blade47/next.js/blob/main/packages/next/tsconfig.build.json#L1-L24).

### Top-Level Type Declarations

Top-level type definitions are orchestrated by `packages/next/index.d.ts`, which references global types, compiled types, styled-jsx types, and core subsystem declaration files before exporting module types. Sources: [packages/next/index.d.ts:1-20](https://github.com/blade47/next.js/blob/main/packages/next/index.d.ts#L1-L20).

```typescript
/// <reference types="./types/global" />
/// <reference types="./types/compiled" />
/// <reference path="./dist/styled-jsx/types/index.d.ts" />
/// <reference path="./app.d.ts" />
/// <reference path="./cache.d.ts" />
/// <reference path="./document.d.ts" />
/// <reference path="./dynamic.d.ts" />
/// <reference path="./error.d.ts" />
/// <reference path="./head.d.ts" />
/// <reference path="./headers.d.ts" />
/// <reference path="./image.d.ts" />
/// <reference path="./link.d.ts" />
/// <reference path="./navigation.d.ts" />
/// <reference path="./router.d.ts" />
/// <reference path="./script.d.ts" />
/// <reference path="./server.d.ts" />

export { default } from './types'
export * from './types'
```
Sources: [packages/next/index.d.ts:1-20](https://github.com/blade47/next.js/blob/main/packages/next/index.d.ts#L1-L20).

The bridge file `packages/next/types.d.ts` directly exports all declarations originating from `./dist/types`, connecting the source declaration outputs to the package consumer interface. Sources: [packages/next/types.d.ts:1-3](https://github.com/blade47/next.js/blob/main/packages/next/types.d.ts#L1-L3).

## Root Module Resolution Facades

### Overview

The `packages/next/` directory provides top-level proxy files that act as resolution facades, forwarding CommonJS `module.exports` and TypeScript type definitions directly to their compiled counterparts inside the `./dist/` directory. These entry points decouple public consumer imports (such as `next/navigation`, `next/client`, or `next/script`) from internal folder layouts and build artifacts. Sources: [packages/next/constants.js:1](https://github.com/blade47/next.js/blob/main/packages/next/constants.js#L1), [packages/next/navigation.js:1](https://github.com/blade47/next.js/blob/main/packages/next/navigation.js#L1).

### Facade Module Mapping

Each top-level JavaScript facade delegates runtime execution to specific compilation outputs within the `dist` folder tree. Similarly, type declaration facades such as `packages/next/constants.d.ts` use ambient wildcard or direct module exports to expose types from the build output. Sources: [packages/next/constants.js:1](https://github.com/blade47/next.js/blob/main/packages/next/constants.js#L1), [packages/next/constants.d.ts:1](https://github.com/blade47/next.js/blob/main/packages/next/constants.d.ts#L1).

| Facade Entry Point | Resolution Target | Exported Domain | Sources |
| :--- | :--- | :--- | :--- |
| `packages/next/constants.js` | `./dist/shared/lib/constants` | Shared application constants | Sources: [packages/next/constants.js:1](https://github.com/blade47/next.js/blob/main/packages/next/constants.js#L1) |
| `packages/next/constants.d.ts` | `./dist/shared/lib/constants` | Shared constant type definitions | Sources: [packages/next/constants.d.ts:1](https://github.com/blade47/next.js/blob/main/packages/next/constants.d.ts#L1) |
| `packages/next/document.js` | `./dist/pages/_document` | Pages router document template | Sources: [packages/next/document.js:1](https://github.com/blade47/next.js/blob/main/packages/next/document.js#L1) |
| `packages/next/app.js` | `./dist/pages/_app` | Pages router application root | Sources: [packages/next/app.js:1](https://github.com/blade47/next.js/blob/main/packages/next/app.js#L1) |
| `packages/next/script.js` | `./dist/client/script` | Client-side script optimization component | Sources: [packages/next/script.js:1](https://github.com/blade47/next.js/blob/main/packages/next/script.js#L1) |
| `packages/next/client.js` | `./dist/client/index` | Client-side runtime entry | Sources: [packages/next/client.js:1](https://github.com/blade47/next.js/blob/main/packages/next/client.js#L1) |
| `packages/next/navigation.js` | `./dist/client/components/navigation` | App router navigation hooks | Sources: [packages/next/navigation.js:1](https://github.com/blade47/next.js/blob/main/packages/next/navigation.js#L1) |
| `packages/next/jest.js` | `./dist/build/jest/jest` | Jest testing integration presets | Sources: [packages/next/jest.js:1](https://github.com/blade47/next.js/blob/main/packages/next/jest.js#L1) |

Sources: [packages/next/constants.js:1](https://github.com/blade47/next.js/blob/main/packages/next/constants.js#L1), [packages/next/constants.d.ts:1](https://github.com/blade47/next.js/blob/main/packages/next/constants.d.ts#L1), [packages/next/document.js:1](https://github.com/blade47/next.js/blob/main/packages/next/document.js#L1), [packages/next/app.js:1](https://github.com/blade47/next.js/blob/main/packages/next/app.js#L1), [packages/next/script.js:1](https://github.com/blade47/next.js/blob/main/packages/next/script.js#L1), [packages/next/client.js:1](https://github.com/blade47/next.js/blob/main/packages/next/client.js#L1), [packages/next/navigation.js:1](https://github.com/blade47/next.js/blob/main/packages/next/navigation.js#L1), [packages/next/jest.js:1](https://github.com/blade47/next.js/blob/main/packages/next/jest.js#L1).

### Runtime Facade Implementation

The implementation across all runtime facades relies on synchronous CommonJS `require` calls pointing to compiled distribution targets. For instance, navigation features load directly from the client components bundle, while document and app templates load from the pages build output. Sources: [packages/next/app.js:1](https://github.com/blade47/next.js/blob/main/packages/next/app.js#L1), [packages/next/navigation.js:1](https://github.com/blade47/next.js/blob/main/packages/next/navigation.js#L1).

```javascript
module.exports = require('./dist/pages/_app')
```
Sources: [packages/next/app.js:1](https://github.com/blade47/next.js/blob/main/packages/next/app.js#L1)

```javascript
module.exports = require('./dist/client/components/navigation')
```
Sources: [packages/next/navigation.js:1](https://github.com/blade47/next.js/blob/main/packages/next/navigation.js#L1)

```javascript
module.exports = require('./dist/build/jest/jest')
```
Sources: [packages/next/jest.js:1](https://github.com/blade47/next.js/blob/main/packages/next/jest.js#L1)

> [!NOTE]
> Resolution facades like `packages/next/navigation.js` and `packages/next/jest.js` decouple consumers from internal build directory structures, allowing the compiler output organization under `./dist/` to change without breaking external import paths like `next/navigation` or `next/jest`. Sources: [packages/next/navigation.js:1](https://github.com/blade47/next.js/blob/main/packages/next/navigation.js#L1), [packages/next/jest.js:1](https://github.com/blade47/next.js/blob/main/packages/next/jest.js#L1).

## Internal Subsystems and API Architecture

### Overview

The codebase organizes its internal API architecture and subsystems under the `packages/next/src/` directory, exposing structured re-exports across server handlers, asynchronous lifecycle hooks, navigation primitives, shared constants, and development tools. These internal modules bridge package-level entry points to specific internal compilation domains. Sources: [packages/next/src/api/server.ts:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/api/server.ts#L1-L2), [packages/next/src/api/constants.ts:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/api/constants.ts#L1-L2), [packages/next/src/api/navigation.ts:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/api/navigation.ts#L1-L2), [packages/next/src/server/after/index.ts:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/server/after/index.ts#L1-L2), [packages/next/src/next-devtools/entrypoint.ts:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/next-devtools/entrypoint.ts#L1-L2).

### Internal Subsystem Modules

The API architecture maps internal directory modules directly to domain-specific source trees via wildcard re-exports. Server-side web APIs delegate through `packages/next/src/api/server.ts` to web export handlers, while navigation functions route through `packages/next/src/api/navigation.ts` to client navigation components. Sources: [packages/next/src/api/server.ts:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/api/server.ts#L1-L2), [packages/next/src/api/navigation.ts:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/api/navigation.ts#L1-L2).

| Internal API Module | Delegation Target | Subsystem Domain | Sources |
| :--- | :--- | :--- | :--- |
| `packages/next/src/api/server.ts` | `../server/web/exports/index` | Server web runtime exports | Sources: [packages/next/src/api/server.ts:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/api/server.ts#L1-L2) |
| `packages/next/src/api/constants.ts` | `../shared/lib/constants` | Shared application constants | Sources: [packages/next/src/api/constants.ts:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/api/constants.ts#L1-L2) |
| `packages/next/src/api/navigation.ts` | `../client/components/navigation` | Client navigation components | Sources: [packages/next/src/api/navigation.ts:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/api/navigation.ts#L1-L2) |
| `packages/next/src/server/after/index.ts` | `./after` | Asynchronous task deferral handlers | Sources: [packages/next/src/server/after/index.ts:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/server/after/index.ts#L1-L2) |
| `packages/next/src/next-devtools/entrypoint.ts` | `./dev-overlay.browser` | Browser development overlay | Sources: [packages/next/src/next-devtools/entrypoint.ts:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/next-devtools/entrypoint.ts#L1-L2) |

Sources: [packages/next/src/api/server.ts:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/api/server.ts#L1-L2), [packages/next/src/api/constants.ts:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/api/constants.ts#L1-L2), [packages/next/src/api/navigation.ts:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/api/navigation.ts#L1-L2), [packages/next/src/server/after/index.ts:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/server/after/index.ts#L1-L2), [packages/next/src/next-devtools/entrypoint.ts:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/next-devtools/entrypoint.ts#L1-L2).

### Facade Delegation Syntax

Internal subsystem entry points utilize wildcard export declarations (`export * from ...`) to aggregate and expose subsystem implementations without hardcoding individual function signatures. Sources: [packages/next/src/api/server.ts:1](https://github.com/blade47/next.js/blob/main/packages/next/src/api/server.ts#L1), [packages/next/src/server/after/index.ts:1](https://github.com/blade47/next.js/blob/main/packages/next/src/server/after/index.ts#L1), [packages/next/src/next-devtools/entrypoint.ts:1](https://github.com/blade47/next.js/blob/main/packages/next/src/next-devtools/entrypoint.ts#L1).

```typescript
export * from '../server/web/exports/index'
```
Sources: [packages/next/src/api/server.ts:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/api/server.ts#L1-L2)

```typescript
export * from './after'
```
Sources: [packages/next/src/server/after/index.ts:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/server/after/index.ts#L1-L2)

```typescript
export * from './dev-overlay.browser'
```
Sources: [packages/next/src/next-devtools/entrypoint.ts:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/next-devtools/entrypoint.ts#L1-L2)

> [!NOTE]
> Devtools entrypoints bind directly to browser-specific overlay targets (`./dev-overlay.browser`), isolating development UI elements from production server bundles. Sources: [packages/next/src/next-devtools/entrypoint.ts:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/next-devtools/entrypoint.ts#L1-L2).

## Compilation Targets and Bundled Dependencies

### Overview

Next.js manages third-party dependencies and compilation outputs through automated Taskfile build routines and dedicated internal bundle shims. Vendor packages such as PostCSS utilities, React runtimes, and webpack sources are compiled, bundled, or aliased into `src/compiled/` to isolate them from external module resolution conflicts and Haste module map warnings. Sources: [packages/next/taskfile.js:1431-1446](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L1431-L1446), [packages/next/taskfile.js:1450-1477](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L1450-L1477).

### Taskfile Build and NCC Compilation Targets

The Taskfile build pipeline invokes `ncc` compilation routines to bundle external libraries into internal distribution targets. For instance, `ncc_icss_utils` resolves `icss-utils`, marks `postcss/lib/parser` as external, and outputs the bundled result directly to `src/compiled/icss-utils`. Sources: [packages/next/taskfile.js:1435-1446](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L1435-L1446).

```javascript
export async function ncc_icss_utils(task, opts) {
  await task
    .source(relative(__dirname, require.resolve('icss-utils')))
    .ncc({
      packageName: 'icss-utils',
      externals: {
        'postcss/lib/parser': 'postcss/lib/parser',
        ...externals,
      },
    })
    .target('src/compiled/icss-utils')
}
```
Sources: [packages/next/taskfile.js:1435-1446](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L1435-L1446)

### Vendor React and Scheduler Copy Execution Walkthrough

The `copy_vendor_react` task processes experimental and standard React channels through a multi-step transformation sequence. 

1. **Channel and Suffix Resolution:** `copy_vendor_react_impl` inspects `opts.experimental` to determine the channel (`experimental-builtin` or `builtin`) and package suffix (`-experimental` or ``). Sources: [packages/next/taskfile.js:1451-1453](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L1451-L1453).
2. **Package Name Rewriting:** `overridePackageName` parses `package.json` files and appends the channel suffix to `json.name` if absent, ensuring Haste module map warnings are avoided. Sources: [packages/next/taskfile.js:1458-1464](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L1458-L1464).
3. **Module Aliasing:** `aliasVendoredReactPackages` replaces string occurrences of `require("react")`, `require("react-dom")`, and `require("scheduler")` inside CommonJS chunks with their `next/dist/compiled/` equivalents containing the appropriate package suffix. Sources: [packages/next/taskfile.js:1479-1493](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L1479-L1493).
4. **AST Parsing and Modification:** `parseFile` utilizes `recast` with an Acorn parser configured for `latest` ECMAScript versions and script source types, enabling AST traversal and identifier replacement via `replaceIdentifiersInAst`. Sources: [packages/next/taskfile.js:1570-1605](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L1570-L1605).

Sources: [packages/next/taskfile.js:1450-1605](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L1450-L1605).

> [!WARNING]
> React DOM CJS files undergo package aliasing but must preserve server-rendering stub mappings, preventing blanket replacement of `react-dom` references with internal compiled paths in contexts where stubs are active. Sources: [packages/next/taskfile.js:1556-1568](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L1556-L1568).

### Internal Bundle Shims and Type Declarations

Internal module resolution relies on type declaration shims located in `packages/next/types/$$compiled.internal.d.ts` alongside webpack facade wrappers. These files map `next/dist/compiled/*` module paths directly to upstream dependency exports or custom wrapper modules. Sources: [packages/next/types/$$compiled.internal.d.ts:487-502](https://github.com/blade47/next.js/blob/main/packages/next/types/%24%24compiled.internal.d.ts#L487-L502), [packages/next/src/bundles/webpack/packages/package.js:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/bundles/webpack/packages/package.js#L1-L2).

| Module Shim / Facade Path | Target Resolution | Purpose | Sources |
| :--- | :--- | :--- | :--- |
| `next/dist/compiled/commander` | `commander` | CLI argument parser module shim | Sources: [packages/next/types/$$compiled.internal.d.ts:487-489](https://github.com/blade47/next.js/blob/main/packages/next/types/%24%24compiled.internal.d.ts#L487-L489) |
| `next/dist/compiled/jest-worker` | `jest-worker` | Worker process farm module shim | Sources: [packages/next/types/$$compiled.internal.d.ts:499-501](https://github.com/blade47/next.js/blob/main/packages/next/types/%24%24compiled.internal.d.ts#L499-L501) |
| `packages/next/src/bundles/webpack/packages/package.js` | `./webpack.js`.package | Webpack package bundle entry facade | Sources: [packages/next/src/bundles/webpack/packages/package.js:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/bundles/webpack/packages/package.js#L1-L2) |
| `packages/next/src/bundles/webpack/packages/sources.js` | `./webpack.js`.sources | Webpack sources bundle entry facade | Sources: [packages/next/src/bundles/webpack/packages/sources.js:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/bundles/webpack/packages/sources.js#L1-L2) |

Sources: [packages/next/types/$$compiled.internal.d.ts:487-502](https://github.com/blade47/next.js/blob/main/packages/next/types/%24%24compiled.internal.d.ts#L487-L502), [packages/next/src/bundles/webpack/packages/package.js:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/bundles/webpack/packages/package.js#L1-L2), [packages/next/src/bundles/webpack/packages/sources.js:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/bundles/webpack/packages/sources.js#L1-L2).

> [!TIP]
> Webpack internal bundling delegates specialized exports like `package` and `sources` through local proxy files into a central `webpack.js` module core, maintaining a clean separation of bundle entry points. Sources: [packages/next/src/bundles/webpack/packages/package.js:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/bundles/webpack/packages/package.js#L1-L2), [packages/next/src/bundles/webpack/packages/sources.js:1-2](https://github.com/blade47/next.js/blob/main/packages/next/src/bundles/webpack/packages/sources.js#L1-L2).

## Related

- [System Overview](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/technical/getting-started/system-overview)
- [Monorepo Workspace](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/technical/getting-started/monorepo-workspace)


## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/llms.txt) for all pages in this wiki.