---
title: "Monorepo Workspace"
description: "The Monorepo Workspace provides the foundational architecture for developing, testing, and building Next.js and its associated tooling across multiple integrated packages and standalone application..."
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/monorepo-workspace"
---

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

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

- [packages/next-codemod/lib/agents-md.ts](https://github.com/blade47/next.js/blob/main/packages/next-codemod/lib/agents-md.ts)
- [packages/next-codemod/bin/__testfixtures__/next-14-installed/pnpm-workspace.yaml](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/next-14-installed/pnpm-workspace.yaml)
- [packages/next-codemod/bin/__testfixtures__/geo-ip-usage/pnpm-workspace.yaml](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/geo-ip-usage/pnpm-workspace.yaml)
- [packages/next-codemod/bin/__testfixtures__/react-18-installed-pure-pages-router/pnpm-workspace.yaml](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/react-18-installed-pure-pages-router/pnpm-workspace.yaml)
- [package.json](https://github.com/blade47/next.js/blob/main/package.json)
- [packages/next-codemod/bin/__testfixtures__/react-19-installed-pure-pages-router/pnpm-workspace.yaml](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/react-19-installed-pure-pages-router/pnpm-workspace.yaml)
- [pnpm-workspace.yaml](https://github.com/blade47/next.js/blob/main/pnpm-workspace.yaml)
- [packages/next/src/cli/next-info.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts)
- [packages/next/src/cli/internal/static-routes-info.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/internal/static-routes-info.ts)
- [packages/next-codemod/bin/__testfixtures__/react-18-installed-pure-app-router/pnpm-workspace.yaml](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/react-18-installed-pure-app-router/pnpm-workspace.yaml)
- [packages/next-codemod/bin/__testfixtures__/react-19-installed-pure-app-router/pnpm-workspace.yaml](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/react-19-installed-pure-app-router/pnpm-workspace.yaml)
- [packages/next-codemod/bin/__testfixtures__/react-18-installed-mixed-router/pnpm-workspace.yaml](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/react-18-installed-mixed-router/pnpm-workspace.yaml)
- [lerna.json](https://github.com/blade47/next.js/blob/main/lerna.json)
- [packages/next-codemod/bin/__testfixtures__/react-19-installed-mixed-router/pnpm-workspace.yaml](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/react-19-installed-mixed-router/pnpm-workspace.yaml)
- [conductor.json](https://github.com/blade47/next.js/blob/main/conductor.json)
- [packages/next/taskfile.js](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js)
- [packages/next-codemod/bin/__testfixtures__/suggest-turbopack/pnpm-workspace.yaml](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/suggest-turbopack/pnpm-workspace.yaml)
- [socket.yaml](https://github.com/blade47/next.js/blob/main/socket.yaml)
- [packages/next-codemod/bin/__testfixtures__/no-geo-ip-usage/pnpm-workspace.yaml](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/no-geo-ip-usage/pnpm-workspace.yaml)
- [packages/next-codemod/bin/__testfixtures__/change-turbo-to-turbopack/pnpm-workspace.yaml](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/change-turbo-to-turbopack/pnpm-workspace.yaml)
- [packages/next-codemod/bin/__testfixtures__/peer-dep-out-of-range/met-range/pnpm-workspace.yaml](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/peer-dep-out-of-range/met-range/pnpm-workspace.yaml)
- [packages/create-next-app/templates/index.ts](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/index.ts)
- [packages/next-codemod/bin/__testfixtures__/peer-dep-out-of-range/pnpm-workspace.yaml](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/peer-dep-out-of-range/pnpm-workspace.yaml)
- [packages/next/src/lib/find-root.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/lib/find-root.ts)
- [packages/next-codemod/bin/__testfixtures__/pnpm-v11-overrides/pnpm-workspace.yaml](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/pnpm-v11-overrides/pnpm-workspace.yaml)
- [packages/next/src/server/lib/chrome-devtools-workspace.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/lib/chrome-devtools-workspace.ts)
- [apps/bundle-analyzer/lib/analyze-data.ts](https://github.com/blade47/next.js/blob/main/apps/bundle-analyzer/lib/analyze-data.ts)
- [packages/next-codemod/lib/handle-package.ts](https://github.com/blade47/next.js/blob/main/packages/next-codemod/lib/handle-package.ts)
- [turbopack/packages/node-module-trace/package.json](https://github.com/blade47/next.js/blob/main/turbopack/packages/node-module-trace/package.json)
- [packages/next/src/bundles/webpack/packages/package.js](https://github.com/blade47/next.js/blob/main/packages/next/src/bundles/webpack/packages/package.js)
</details>

## Overview

The Monorepo Workspace provides the foundational architecture for developing, testing, and building Next.js and its associated tooling across multiple integrated packages and standalone applications. It establishes strict workspace configurations, automated build pipelines, and runtime discovery utilities to seamlessly coordinate dependencies across diverse package managers and orchestrators. Sources: [conductor.json:1-4](https://github.com/blade47/next.js/blob/main/conductor.json#L1-L4), [pnpm-workspace.yaml:1-9](https://github.com/blade47/next.js/blob/main/pnpm-workspace.yaml#L1-L9)

By enforcing structured package boundaries, deterministic lockfile resolution, and comprehensive diagnostic inspection, the workspace architecture solves complex dependency management and bundling challenges inherent in large-scale JavaScript and Rust-based hybrid repositories. Sources: [packages/next/src/lib/find-root.ts:34-65](https://github.com/blade47/next.js/blob/main/packages/next/src/lib/find-root.ts#L34-L65), [packages/next/src/cli/internal/static-routes-info.ts:1-16](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/internal/static-routes-info.ts#L1-L16)

## Monorepo Layout and Workspace Configuration

### Workspace Management Architecture

The root workspace architecture organizes the repository by integrating `pnpm`, `Lerna`, and `Conductor` orchestrations to govern dependency layout, package publishing, and developer environment management. These orchestration layers define precise package globs, publish workflows, environment defaults, and security constraints across the repository. Sources: [pnpm-workspace.yaml:1-9](https://github.com/blade47/next.js/blob/main/pnpm-workspace.yaml#L1-L9), [lerna.json:1-19](https://github.com/blade47/next.js/blob/main/lerna.json#L1-L19), [conductor.json:1-14](https://github.com/blade47/next.js/blob/main/conductor.json#L1-L14)

### PNPM Workspace Layout

The `pnpm-workspace.yaml` configuration dictates how workspaces are scanned and resolved across applications, packages, benchmarks, and Turbopack Rust-to-JS bindings. Sources: [pnpm-workspace.yaml:1-8](https://github.com/blade47/next.js/blob/main/pnpm-workspace.yaml#L1-L8)

| Package Glob Pattern | Target Component / Subsystem | Sources |
| :--- | :--- | :--- |
| `apps/*` | Standalone applications and consumer examples | [pnpm-workspace.yaml:2-2](https://github.com/blade47/next.js/blob/main/pnpm-workspace.yaml#L2-L2) |
| `packages/*` | Core framework packages and shared libraries | [pnpm-workspace.yaml:3-3](https://github.com/blade47/next.js/blob/main/pnpm-workspace.yaml#L3-L3) |
| `bench/*` | Performance benchmark suites | [pnpm-workspace.yaml:4-4](https://github.com/blade47/next.js/blob/main/pnpm-workspace.yaml#L4-L4) |
| `crates/*/js` | Rust crate JavaScript bindings | [pnpm-workspace.yaml:5-5](https://github.com/blade47/next.js/blob/main/pnpm-workspace.yaml#L5-L5) |
| `turbopack/crates/*/js` | Turbopack Rust crate JavaScript bindings | [pnpm-workspace.yaml:6-6](https://github.com/blade47/next.js/blob/main/pnpm-workspace.yaml#L6-L6) |
| `turbopack/crates/turbopack-tests/tests/execution` | Turbopack execution test suites | [pnpm-workspace.yaml:7-7](https://github.com/blade47/next.js/blob/main/pnpm-workspace.yaml#L7-L7) |
| `turbopack/packages/*` | Turbopack package ecosystem | [pnpm-workspace.yaml:8-8](https://github.com/blade47/next.js/blob/main/pnpm-workspace.yaml#L8-L8) |

Sources: [pnpm-workspace.yaml:1-8](https://github.com/blade47/next.js/blob/main/pnpm-workspace.yaml#L1-L8)

> [!IMPORTANT]
> The pnpm workspace disables update notifications via `updateNotifier: false` and hoists specific eslint dependencies using `publicHoistPattern: ['*eslint*']` while enforcing security boundaries with `blockExoticSubdeps: true` and a 48-hour minimum release age (`minimumReleaseAge: 2880`). Sources: [pnpm-workspace.yaml:9-11](https://github.com/blade47/next.js/blob/main/pnpm-workspace.yaml#L9-L11), [pnpm-workspace.yaml:34-35](https://github.com/blade47/next.js/blob/main/pnpm-workspace.yaml#L34-L35)

### Lerna Versioning and Publishing

Lerna manages multi-package version coordination and publication pipelines at the repository root. It relies on `pnpm` as the underlying `npmClient` and restricts publishing actions to the `canary` branch targeting the public npm registry. Sources: [lerna.json:1-17](https://github.com/blade47/next.js/blob/main/lerna.json#L1-L17)

| Lerna Configuration Property | Value / Scope | Sources |
| :--- | :--- | :--- |
| `npmClient` | `pnpm` | [lerna.json:2-2](https://github.com/blade47/next.js/blob/main/lerna.json#L2-L2) |
| `packages` | `packages/*` | [lerna.json:3-5](https://github.com/blade47/next.js/blob/main/lerna.json#L3-L5) |
| `command.version.exact` | `true` | [lerna.json:7-9](https://github.com/blade47/next.js/blob/main/lerna.json#L7-L9) |
| `command.publish.npmClient` | `npm` | [lerna.json:10-11](https://github.com/blade47/next.js/blob/main/lerna.json#L10-L11) |
| `command.publish.allowBranch` | `["canary"]` | [lerna.json:12-14](https://github.com/blade47/next.js/blob/main/lerna.json#L12-L14) |
| `command.publish.registry` | `https://registry.npmjs.org/` | [lerna.json:15-15](https://github.com/blade47/next.js/blob/main/lerna.json#L15-L15) |
| `version` | `16.3.0-canary.51` | [lerna.json:18-18](https://github.com/blade47/next.js/blob/main/lerna.json#L18-L18) |

Sources: [lerna.json:1-18](https://github.com/blade47/next.js/blob/main/lerna.json#L1-L18)

### Conductor Orchestration and Environment

The Conductor configuration establishes workspace environment defaults, lifecycle scripts, worktree branches, and developer operational recommendations. Sources: [conductor.json:1-23](https://github.com/blade47/next.js/blob/main/conductor.json#L1-L23)

> [!CAUTION]
> Never execute `pnpm build` while `pnpm dev` is active within the workspace, as concurrent builds cause file corruption in Rust artifacts and bundled outputs. Sources: [conductor.json:21-21](https://github.com/blade47/next.js/blob/main/conductor.json#L21-L21)

Sources: [conductor.json:1-24](https://github.com/blade47/next.js/blob/main/conductor.json#L1-L24)

## Workspace Root and Lockfile Discovery

### Overview

Workspace root and lockfile discovery mechanisms locate project boundaries, detect active package managers, and traverse directory trees to establish correct execution and build roots. Sources: [packages/next/src/lib/find-root.ts:5-65](https://github.com/blade47/next.js/blob/main/packages/next/src/lib/find-root.ts#L5-L65), [packages/next-codemod/lib/handle-package.ts:55-87](https://github.com/blade47/next-codemod/lib/handle-package.ts#L55-L87)

### Workspace Root Discovery and Traversal Algorithm

#### Traversal Mechanics

The runtime discovery process identifies workspace boundaries by searching upward from the current working directory (`cwd`) for workspace configuration files and lockfiles using `find-up`. Sources: [packages/next/src/lib/find-root.ts:5-32](https://github.com/blade47/next.js/blob/main/packages/next/src/lib/find-root.ts#L5-L32)

#### Call-Chain Execution Walkthrough

The workspace discovery pipeline executes through the following sequence:
1. `findRootDirAndLockFiles(cwd)` initiates root and lockfile gathering. Sources: [packages/next/src/lib/find-root.ts:34-38](https://github.com/blade47/next.js/blob/main/packages/next/src/lib/find-root.ts#L34-L38)
2. `findWorkRoot(cwd)` runs first, executing an upward search prioritized for `pnpm-workspace.yaml` before checking other lockfile types to prevent accidental inclusion of nested lockfiles. Sources: [packages/next/src/lib/find-root.ts:5-32](https://github.com/blade47/next.js/blob/main/packages/next/src/lib/find-root.ts#L5-L32)
3. If a lockfile or workspace file is found, `findRootDirAndLockFiles` enters a `while (true)` traversal loop, checking parent directories via `dirname(currentDir)` until reaching the filesystem root (`parentDir === currentDir`) or finding additional parent lockfiles. Sources: [packages/next/src/lib/find-root.ts:46-59](https://github.com/blade47/next.js/blob/main/packages/next/src/lib/find-root.ts#L46-L59)
4. Finally, `rootDir` is resolved as `dirname(lockFiles[lockFiles.length - 1])`. Sources: [packages/next/src/lib/find-root.ts:63-63](https://github.com/blade47/next.js/blob/main/packages/next/src/lib/find-root.ts#L63-L63)

> [!NOTE]
> `findWorkRoot` explicitly checks for `pnpm-workspace.yaml` prior to searching for general lockfiles to ensure that root configuration files take precedence over nested application lockfiles. Sources: [packages/next/src/lib/find-root.ts:6-18](https://github.com/blade47/next.js/blob/main/packages/next/src/lib/find-root.ts#L6-L18)

Sources: [packages/next/src/lib/find-root.ts:5-65](https://github.com/blade47/next.js/blob/main/packages/next/src/lib/find-root.ts#L5-L65)

### Multi-Manager Detection and Lockfile Handling

Package managers are identified through lockfile inspection or environment variables. The codebase handles multiple package managers and supports duplicate lockfile warnings when nested configurations are detected. Sources: [packages/next-codemod/lib/handle-package.ts:55-87](https://github.com/blade47/next-codemod/lib/handle-package.ts#L55-L87)

| Lockfile / Config Name | Detected Package Manager | Sources |
| :--- | :--- | :--- |
| `package-lock.json` | `npm` | [packages/next-codemod/lib/handle-package.ts:69-70](https://github.com/blade47/next-codemod/lib/handle-package.ts#L69-L70) |
| `yarn.lock` | `yarn` | [packages/next-codemod/lib/handle-package.ts:71-72](https://github.com/blade47/next-codemod/lib/handle-package.ts#L71-L72) |
| `pnpm-lock.yaml` / `pnpm-workspace.yaml` | `pnpm` | [packages/next-codemod/lib/handle-package.ts:73-74](https://github.com/blade47/next-codemod/lib/handle-package.ts#L73-L74), [packages/next/src/lib/find-root.ts:8-14](https://github.com/blade47/next.js/blob/main/packages/next/src/lib/find-root.ts#L8-L14) |
| `bun.lock` / `bun.lockb` | `bun` | [packages/next-codemod/lib/handle-package.ts:75-77](https://github.com/blade47/next-codemod/lib/handle-package.ts#L75-L77) |

> [!WARNING]
> If multiple lockfiles are detected during traversal (`lockFiles.length > 1`), Next.js emits a warning selecting the topmost lockfile directory as the root and instructing developers to configure `turbopack.root` or `outputFileTracingRoot` to silence the warning. Sources: [packages/next/src/lib/find-root.ts:67-93](https://github.com/blade47/next.js/blob/main/packages/next/src/lib/find-root.ts#L67-L93)

Sources: [packages/next/src/lib/find-root.ts:34-94](https://github.com/blade47/next.js/blob/main/packages/next/src/lib/find-root.ts#L34-L94), [packages/next-codemod/lib/handle-package.ts:55-87](https://github.com/blade47/next-codemod/lib/handle-package.ts#L55-L87)

## Workspace Packages and Applications Structure

### Overview

The workspace architecture organizes source code across generation templates, analytical standalone applications, and experimental tracing packages. Scaffolding utilities within `packages/create-next-app` configure project templates dynamically, translating user flags into workspace configurations, package manager rules, and dependency structures. Sources: [packages/create-next-app/templates/index.ts:1-435](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/index.ts)

### Template Generation and Package Configuration

The template installation process handled by `installTemplate` manages file copying, compiler integration, import alias normalization, and manifest serialization. It maps user-selected bundlers, linters, and package managers directly into `package.json` configurations and workspace files. Sources: [packages/create-next-app/templates/index.ts:48-408](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/index.ts)

| Configuration Flag | Target File | Modification Logic | Sources |
| :--- | :--- | :--- | :--- |
| `bundler: Bundler.Rspack` | `next.config.mjs` / `next.config.ts` | Wraps default export with `withRspack(nextConfig)` and injects `next-rspack` dependency | [packages/create-next-app/templates/index.ts:97-110](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/index.ts#L97-L110), [packages/create-next-app/templates/index.ts:258-260](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/index.ts#L258-L260) |
| `reactCompiler: true` | `next.config.mjs` / `next.config.ts` | Inserts `reactCompiler: true` into config options and adds `babel-plugin-react-compiler` | [packages/create-next-app/templates/index.ts:112-125](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/index.ts#L112-L125), [packages/create-next-app/templates/index.ts:262-264](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/index.ts#L262-L264) |
| `importAlias` | `tsconfig.json` / `jsconfig.json` & Source Files | Replaces `@/*` paths with custom alias and recursively updates matching imports across source files | [packages/create-next-app/templates/index.ts:127-177](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/index.ts#L127-L177) |
| `srcDir: true` | Target root directory | Creates `src/` directory, relocates default app directories (`app`, `pages`, `styles`), and updates entry points | [packages/create-next-app/templates/index.ts:179-211](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/index.ts#L179-L211) |
| `packageManager: pnpm` | `pnpm-workspace.yaml` | Writes workspace restriction maps such as `allowBuilds` or `ignoredBuiltDependencies` for packages like `sharp` and `unrs-resolver` | [packages/create-next-app/templates/index.ts:333-376](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/index.ts#L333-L376) |

> [!WARNING]
> When `packageManager` is set to `bun`, the generated manifest automatically populates both `ignoreScripts` and `trustedDependencies` with `sharp` and `unrs-resolver` to suppress installation warnings and satisfy Bun security requirements. Sources: [packages/create-next-app/templates/index.ts:391-402](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/index.ts#L391-L402)

Sources: [packages/create-next-app/templates/index.ts:48-408](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/index.ts#L48-L408)

### Bundle Analysis and Binary Data Structures

#### ArrayBuffer Ingestion Architecture

The workspace includes dedicated analysis tools under `apps/bundle-analyzer` designed to ingest structured build outputs from Rust compilers. The parser processes binary chunks and module graphs via `ModulesData` and `AnalyzeData` classes using `DataView` interfaces over raw ArrayBuffers. Sources: [apps/bundle-analyzer/lib/analyze-data.ts:1-203](https://github.com/blade47/next.js/blob/main/apps/bundle-analyzer/lib/analyze-data.ts#L1-L203)

#### Call-Chain Execution Walkthrough

The bundle analysis data-loading sequence proceeds as follows:
1. `new ModulesData(modulesArrayBuffer)` receives the raw binary buffer. Sources: [apps/bundle-analyzer/lib/analyze-data.ts:65-65](https://github.com/blade47/next.js/blob/main/apps/bundle-analyzer/lib/analyze-data.ts#L65-L65)
2. `DataView` extracts a 32-bit big-endian integer representing the JSON header length from offset `0`. Sources: [apps/bundle-analyzer/lib/analyze-data.ts:67-68](https://github.com/blade47/next.js/blob/main/apps/bundle-analyzer/lib/analyze-data.ts#L67-L68)
3. `TextDecoder('utf-8')` decodes the subsequent JSON byte range into the `ModulesDataHeader` schema. Sources: [apps/bundle-analyzer/lib/analyze-data.ts:69-75](https://github.com/blade47/next.js/blob/main/apps/bundle-analyzer/lib/analyze-data.ts#L69-L75)
4. The remaining binary segment starting at `4 + modulesJsonLength` is wrapped into a secondary `DataView` (`modulesBinaryData`) for efficient edge-index lookups without full deserialization. Sources: [apps/bundle-analyzer/lib/analyze-data.ts:76-80](https://github.com/blade47/next.js/blob/main/apps/bundle-analyzer/lib/analyze-data.ts#L76-L80)
5. Finally, `pathToModuleIndex` mapping constructs an index lookup table linking file paths to module indices. Sources: [apps/bundle-analyzer/lib/analyze-data.ts:82-92](https://github.com/blade47/next.js/blob/main/apps/bundle-analyzer/lib/analyze-data.ts#L82-L92)

> [!NOTE]
> Edge relationships such as `moduleDependents`, `asyncModuleDependents`, and `tracedModuleDependents` are read lazily via `readEdgesDataAtIndex` by computing variable-length offset boundaries directly from the binary data view. Sources: [apps/bundle-analyzer/lib/analyze-data.ts:108-198](https://github.com/blade47/next.js/blob/main/apps/bundle-analyzer/lib/analyze-data.ts#L108-L198)

Sources: [apps/bundle-analyzer/lib/analyze-data.ts:60-203](https://github.com/blade47/next.js/blob/main/apps/bundle-analyzer/lib/analyze-data.ts#L60-L203)

### Experimental Node Module Tracing Package

The `turbopack/packages/node-module-trace` package operates as an experimental dependency file tracing utility within the monorepo structure. Publishing under the `@vercel/experimental-nft` package name with alias `node-file-trace`, it exposes metadata configuration specifying public access and MIT licensing rules. Sources: [turbopack/packages/node-module-trace/package.json:1-10](https://github.com/blade47/next.js/blob/main/turbopack/packages/node-module-trace/package.json#L1-L10)

Sources: [turbopack/packages/node-module-trace/package.json:1-10](https://github.com/blade47/next.js/blob/main/turbopack/packages/node-module-trace/package.json#L1-L10)

## Task Automation and Bundle Pipelines

### Overview

Task automation and bundle pipelines within the monorepo rely on programmatic taskfile execution and dedicated precompiled dependency distribution pipelines. Sources: [packages/next/taskfile.js:2752-2795](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L2752-L2795)

### Taskfile Execution and Watch Pipelines

#### Watch Initialization

The default taskfile export initializes a development build lifecycle by clearing the `dist` directory, triggering the main `build` task, and registering active file watchers across source subdirectories. Each watcher maps specific source paths to corresponding compilation targets with development options enabled (`opts = { dev: true }`). Sources: [packages/next/taskfile.js:2752-2755](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L2752-L2755)

#### Call-Chain Execution Walkthrough

The default watcher registration sequence proceeds as follows:
1. `export default async function (task)` initializes the task context and clears the `dist` target directory via `task.clear('dist')`. Sources: [packages/next/taskfile.js:2752-2754](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L2752-L2754)
2. `task.start('build', opts)` executes the initial compilation pipeline. Sources: [packages/next/taskfile.js:2755-2755](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L2755-L2755)
3. `task.watch('src/bin', 'bin', opts)` registers incremental rebuild bindings for binary CLI entry points. Sources: [packages/next/taskfile.js:2756-2756](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L2756-L2756)
4. `task.watch('src/server', ['server', 'server_esm', 'server_wasm'], opts)` binds server source modifications to CommonJS, ESM, and WebAssembly compilation targets. Sources: [packages/next/taskfile.js:2758-2758](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L2758-L2758)
5. `task.watch('src/shared', [...], opts)` dispatches shared module updates across re-exported, ESM, and standard target pipelines. Sources: [packages/next/taskfile.js:2790-2794](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L2790-L2794)

> [!NOTE]
> The shared source watcher explicitly excludes test files (`**/*.test.js`, `**/*.test.ts`, `**/*.test.tsx`, `**/*.test.d.ts`) and core configuration modules like `config`, `constants`, `dynamic`, `app-dynamic`, `head`, and `runtime-config`. Sources: [packages/next/taskfile.js:2797-2805](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L2797-L2805)

Sources: [packages/next/taskfile.js:2752-2807](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L2752-L2807)

### Precompiled Dependency and Vendor Distribution Pipelines

Vendor distribution pipelines manage external packages such as React, React DOM, Scheduler, and PostCSS plugins by copying compiled CommonJS artifacts, rewriting package manifests, and removing redundant distribution files. For instance, `copy_vendor_react` processes experimental or standard channels via `overridePackageName` and `aliasVendoredReactPackages`. Sources: [packages/next/taskfile.js:1435-1493](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L1435-L1493)

| Item to Remove | Target Directory | Purpose | Sources |
| :--- | :--- | :--- | :--- |
| `static.js` | `src/compiled/react-dom*` | Removes unused static server entry point | [packages/next/taskfile.js:1620-1626](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L1620-L1626) |
| `static.browser.js` | `src/compiled/react-dom*` | Removes browser-specific static rendering artifact | [packages/next/taskfile.js:1620-1626](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L1620-L1626) |
| `unstable_testing.js` | `src/compiled/react-dom*` | Strips unstable testing entry point | [packages/next/taskfile.js:1620-1627](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L1620-L1627) |
| `test-utils.js` | `src/compiled/react-dom*` | Strips test utility module | [packages/next/taskfile.js:1620-1628](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L1620-L1628) |
| `server.bun.js` | `src/compiled/react-dom*` | Removes Bun runtime server bundle | [packages/next/taskfile.js:1620-1629](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L1620-L1629) |
| `unstable_server-external-runtime.js` | `src/compiled/react-dom*` | Removes unstable external runtime helper | [packages/next/taskfile.js:1620-1634](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L1620-L1634) |

Sources: [packages/next/taskfile.js:1620-1639](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L1620-L1639)

> [!WARNING]
> When compiling error codes via `check_error_codes`, failures in CI environments automatically output a notification instructing developers to run `pnpm build` or `pnpm update-error-codes` to synchronize `errors.json` before forcing a process exit with code `1`. Sources: [packages/next/taskfile.js:2733-2750](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L2733-L2750)

Sources: [packages/next/taskfile.js:1435-1639](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L1435-L1639), [packages/next/taskfile.js:2733-2750](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js#L2733-L2750)

## Workspace Diagnostics and Route Analytics

### Overview

Monorepo diagnostics and analytics combine command-line inspection utilities, static route measurement, and live Chrome DevTools workspace integration to provide insight into a built application's structure and environment. Sources: [packages/next/src/cli/next-info.ts:1-169](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L1-L169), [packages/next/src/cli/internal/static-routes-info.ts:1-16](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/internal/static-routes-info.ts#L1-L16)

### Diagnostic Inspection and Environment Reporting

The `next info` CLI utility (`printInfo()`) collects environment parameters, binary versions, and package versions to standard output. Sources: [packages/next/src/cli/next-info.ts:96-169](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L96-L169)

| Package Key | Resolution Source | Fallback / Default | Sources |
| :--- | :--- | :--- | :--- |
| `next` | `getPackageVersion('next')` | `'N/A'` | [packages/next/src/cli/next-info.ts:55-61](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L55-L61), [packages/next/src/cli/next-info.ts:97-97](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L97-L97) |
| `eslint-config-next` | `getPackageVersion('eslint-config-next')` | `'N/A'` | [packages/next/src/cli/next-info.ts:55-61](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L55-L61), [packages/next/src/cli/next-info.ts:137-137](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L137-L137) |
| `react` | `getPackageVersion('react')` | `'N/A'` | [packages/next/src/cli/next-info.ts:55-61](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L55-L61), [packages/next/src/cli/next-info.ts:138-138](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L138-L138) |
| `react-dom` | `getPackageVersion('react-dom')` | `'N/A'` | [packages/next/src/cli/next-info.ts:55-61](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L55-L61), [packages/next/src/cli/next-info.ts:139-139](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L139-L139) |
| `typescript` | `getPackageVersion('typescript')` | `'N/A'` | [packages/next/src/cli/next-info.ts:55-61](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L55-L61), [packages/next/src/cli/next-info.ts:140-140](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L140-L140) |
| `next-rspack` | `getPackageVersion('next-rspack')` (Conditional on `process.env.NEXT_RSPACK`) | `'N/A'` | [packages/next/src/cli/next-info.ts:55-61](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L55-L61), [packages/next/src/cli/next-info.ts:142-145](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L142-L145) |

Sources: [packages/next/src/cli/next-info.ts:55-145](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L55-L145)

> [!WARNING]
> When `printInfo()` checks the package registry for release staleness via `fetch`, network failures do not halt execution. Instead, they emit a yellow-highlighted warning instructing the user to verify against the latest canary release. Sources: [packages/next/src/cli/next-info.ts:105-133](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L105-L133)

### Static Route Analysis Pipeline

The `next internal static-routes-info` command performs static bundle size reporting across built routes without executing application code. Sources: [packages/next/src/cli/internal/static-routes-info.ts:1-16](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/internal/static-routes-info.ts#L1-L16)

| Category Constant | Human-Readable Label | Target File Classification | Sources |
| :--- | :--- | :--- | :--- |
| `clientJs` | Client JS | Client-side JavaScript bundles and chunks | [packages/next/src/cli/internal/static-routes-info.ts:62-62](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/internal/static-routes-info.ts#L62-L62), [packages/next/src/cli/internal/static-routes-info.ts:73-73](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/internal/static-routes-info.ts#L73-L73) |
| `clientCss` | Client CSS | Client stylesheets | [packages/next/src/cli/internal/static-routes-info.ts:63-63](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/internal/static-routes-info.ts#L63-L63), [packages/next/src/cli/internal/static-routes-info.ts:74-74](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/internal/static-routes-info.ts#L74-L74) |
| `clientMaps` | Client Source Maps | Client-side source map files (.map) | [packages/next/src/cli/internal/static-routes-info.ts:64-64](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/internal/static-routes-info.ts#L64-L64), [packages/next/src/cli/internal/static-routes-info.ts:75-75](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/internal/static-routes-info.ts#L75-L75) |
| `serverBundled` | Server Bundled JS | Server-side bundled JavaScript files | [packages/next/src/cli/internal/static-routes-info.ts:65-65](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/internal/static-routes-info.ts#L65-L65), [packages/next/src/cli/internal/static-routes-info.ts:76-76](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/internal/static-routes-info.ts#L76-L76) |
| `serverUnbundled` | Server Unbundled | Traced external dependencies (e.g., `node_modules`) | [packages/next/src/cli/internal/static-routes-info.ts:66-66](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/internal/static-routes-info.ts#L66-L66), [packages/next/src/cli/internal/static-routes-info.ts:77-77](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/internal/static-routes-info.ts#L77-L77) |
| `serverMaps` | Server Source Maps | Server-side source map files | [packages/next/src/cli/internal/static-routes-info.ts:67-67](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/internal/static-routes-info.ts#L67-L67), [packages/next/src/cli/internal/static-routes-info.ts:78-78](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/internal/static-routes-info.ts#L78-L78) |

Sources: [packages/next/src/cli/internal/static-routes-info.ts:61-79](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/internal/static-routes-info.ts#L61-L79)

> [!TIP]
> Sorting keys available via `--sort` include `name`, `client`, `client-js`, `client-css`, `client-map`, `server`, `server-bundled-js`, `server-unbundled`, `server-map`, and `total`. Sources: [packages/next/src/cli/internal/static-routes-info.ts:36-47](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/internal/static-routes-info.ts#L36-L47)

### Chrome DevTools Workspace Integration

The server exposes an endpoint to support Chrome DevTools Workspaces via `isChromeDevtoolsWorkspaceUrl(pathname)` matching `/.well-known/appspecific/com.chrome.devtools.json`. Sources: [packages/next/src/server/lib/chrome-devtools-workspace.ts:1-31](https://github.com/blade47/next.js/blob/main/packages/next/src/server/lib/chrome-devtools-workspace.ts#L1-L31)

```typescript
async function getChromeDevtoolsWorkspace(
  root: string,
  configDistDir: string
): Promise<ChromeDevtoolsWorkspace> {
  if (workspaceUUID === null) {
    const distDir = path.join(root, configDistDir)
    const cacheBaseDir = getStorageDirectory(distDir)

    if (cacheBaseDir === undefined) {
      workspaceUUID = randomUUID()
    } else {
      const cachedUUIDPath = path.join(
        cacheBaseDir,
        'chrome-devtools-workspace-uuid'
      )
      try {
        workspaceUUID = await fs.promises.readFile(cachedUUIDPath, 'utf8')
      } catch {
        workspaceUUID = randomUUID()

        try {
          await fs.promises.writeFile(cachedUUIDPath, workspaceUUID, 'utf8')
        } catch (cause) {
          console.warn(
            new Error(
              'Failed to persist Chrome DevTools workspace UUID. The Chrome DevTools Workspace needs to be reconnected after the next page reload.',
              { cause }
            )
          )
        }
      }
    }
  }

  return {
    workspace: {
      uuid: workspaceUUID,
      root,
    },
  }
}
```

Sources: [packages/next/src/server/lib/chrome-devtools-workspace.ts:46-89](https://github.com/blade47/next.js/blob/main/packages/next/src/server/lib/chrome-devtools-workspace.ts#L46-L89)

> [!IMPORTANT]
> The workspace UUID is held in a module-level variable (`workspaceUUID`) to remain constant throughout the server's lifecycle. Sources: [packages/next/src/server/lib/chrome-devtools-workspace.ts:10-10](https://github.com/blade47/next.js/blob/main/packages/next/src/server/lib/chrome-devtools-workspace.ts#L10-L10)

## Multi-Workspace Fixtures and Compatibility Matrix

### Fixture System Overview

The test fixtures under `packages/next-codemod/bin/__testfixtures__/` supply a matrix of workspace configurations and compatibility scenarios for validating codemod operations across Next.js versions, React major versions, router structures, and package manager feature sets. Sources: [packages/next-codemod/bin/__testfixtures__/next-14-installed/pnpm-workspace.yaml:1-1](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/next-14-installed/pnpm-workspace.yaml#L1-L1), [packages/next-codemod/bin/__testfixtures__/pnpm-v11-overrides/pnpm-workspace.yaml:1-4](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/pnpm-v11-overrides/pnpm-workspace.yaml#L1-L4)

### Compatibility Matrix and Workspace Fixture Catalog

The test suite organizes fixtures into specific categories reflecting dependency setups, feature flags, and package manager options. Sources: [packages/next-codemod/bin/__testfixtures__/next-14-installed/pnpm-workspace.yaml:1-1](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/next-14-installed/pnpm-workspace.yaml#L1-L1)

| Fixture Path | Focus Area / Scenario | Workspace Configuration | Sources |
|---|---|---|---|
| `packages/next-codemod/bin/__testfixtures__/next-14-installed/` | Next.js version 14 migration baseline | Empty workspace root | [packages/next-codemod/bin/__testfixtures__/next-14-installed/pnpm-workspace.yaml:1-1](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/next-14-installed/pnpm-workspace.yaml#L1-L1) |
| `packages/next-codemod/bin/__testfixtures__/geo-ip-usage/` | IP geolocation API usage detection | Empty workspace root | [packages/next-codemod/bin/__testfixtures__/geo-ip-usage/pnpm-workspace.yaml:1-1](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/geo-ip-usage/pnpm-workspace.yaml#L1-L1) |
| `packages/next-codemod/bin/__testfixtures__/no-geo-ip-usage/` | Absence of geolocation API usage | Empty workspace root | [packages/next-codemod/bin/__testfixtures__/no-geo-ip-usage/pnpm-workspace.yaml:1-1](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/no-geo-ip-usage/pnpm-workspace.yaml#L1-L1) |
| `packages/next-codemod/bin/__testfixtures__/react-18-installed-pure-pages-router/` | React 18 with Pages router exclusively | Empty workspace root | [packages/next-codemod/bin/__testfixtures__/react-18-installed-pure-pages-router/pnpm-workspace.yaml:1-1](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/react-18-installed-pure-pages-router/pnpm-workspace.yaml#L1-L1) |
| `packages/next-codemod/bin/__testfixtures__/react-19-installed-pure-pages-router/` | React 19 with Pages router exclusively | Empty workspace root | [packages/next-codemod/bin/__testfixtures__/react-19-installed-pure-pages-router/pnpm-workspace.yaml:1-1](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/react-19-installed-pure-pages-router/pnpm-workspace.yaml#L1-L1) |
| `packages/next-codemod/bin/__testfixtures__/react-18-installed-pure-app-router/` | React 18 with App router exclusively | Empty workspace root | [packages/next-codemod/bin/__testfixtures__/react-18-installed-pure-app-router/pnpm-workspace.yaml:1-1](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/react-18-installed-pure-app-router/pnpm-workspace.yaml#L1-L1) |
| `packages/next-codemod/bin/__testfixtures__/react-19-installed-pure-app-router/` | React 19 with App router exclusively | Empty workspace root | [packages/next-codemod/bin/__testfixtures__/react-19-installed-pure-app-router/pnpm-workspace.yaml:1-1](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/react-19-installed-pure-app-router/pnpm-workspace.yaml#L1-L1) |
| `packages/next-codemod/bin/__testfixtures__/react-18-installed-mixed-router/` | React 18 with mixed Pages and App routers | Empty workspace root | [packages/next-codemod/bin/__testfixtures__/react-18-installed-mixed-router/pnpm-workspace.yaml:1-1](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/react-18-installed-mixed-router/pnpm-workspace.yaml#L1-L1) |
| `packages/next-codemod/bin/__testfixtures__/react-19-installed-mixed-router/` | React 19 with mixed Pages and App routers | Empty workspace root | [packages/next-codemod/bin/__testfixtures__/react-19-installed-mixed-router/pnpm-workspace.yaml:1-1](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/react-19-installed-mixed-router/pnpm-workspace.yaml#L1-L1) |
| `packages/next-codemod/bin/__testfixtures__/suggest-turbopack/` | Turbopack adoption suggestion | Empty workspace root | [packages/next-codemod/bin/__testfixtures__/suggest-turbopack/pnpm-workspace.yaml:1-1](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/suggest-turbopack/pnpm-workspace.yaml#L1-L1) |
| `packages/next-codemod/bin/__testfixtures__/change-turbo-to-turbopack/` | CLI flag migration from turbo to turbopack | Empty workspace root | [packages/next-codemod/bin/__testfixtures__/change-turbo-to-turbopack/pnpm-workspace.yaml:1-1](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/change-turbo-to-turbopack/pnpm-workspace.yaml#L1-L1) |
| `packages/next-codemod/bin/__testfixtures__/peer-dep-out-of-range/` | Peer dependency mismatch scenarios | Empty workspace root | [packages/next-codemod/bin/__testfixtures__/peer-dep-out-of-range/pnpm-workspace.yaml:1-1](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/peer-dep-out-of-range/pnpm-workspace.yaml#L1-L1) |
| `packages/next-codemod/bin/__testfixtures__/pnpm-v11-overrides/` | PNPM v11 build controls and overrides | Explicit `allowBuilds` configuration | [packages/next-codemod/bin/__testfixtures__/pnpm-v11-overrides/pnpm-workspace.yaml:1-4](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/pnpm-v11-overrides/pnpm-workspace.yaml#L1-L4) |

Sources: [packages/next-codemod/bin/__testfixtures__/next-14-installed/pnpm-workspace.yaml:1-1](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/next-14-installed/pnpm-workspace.yaml#L1-L1), [packages/next-codemod/bin/__testfixtures__/pnpm-v11-overrides/pnpm-workspace.yaml:1-4](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/pnpm-v11-overrides/pnpm-workspace.yaml#L1-L4)

### PNPM v11 Workspace Build Constraints

The `pnpm-v11-overrides` fixture defines explicit package build permissions via the `allowBuilds` mapping in `pnpm-workspace.yaml`. Sources: [packages/next-codemod/bin/__testfixtures__/pnpm-v11-overrides/pnpm-workspace.yaml:1-4](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/pnpm-v11-overrides/pnpm-workspace.yaml#L1-L4)

```yaml
allowBuilds:
  sharp: false
  unrs-resolver: false
```

Sources: [packages/next-codemod/bin/__testfixtures__/pnpm-v11-overrides/pnpm-workspace.yaml:1-4](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/pnpm-v11-overrides/pnpm-workspace.yaml#L1-L4)

> [!WARNING]
> Setting build permissions to `false` in `allowBuilds` prevents native postinstall compilation scripts from executing for packages such as `sharp` and `unrs-resolver`, which can affect native module loading during workspace test executions. Sources: [packages/next-codemod/bin/__testfixtures__/pnpm-v11-overrides/pnpm-workspace.yaml:1-4](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/__testfixtures__/pnpm-v11-overrides/pnpm-workspace.yaml#L1-L4)

## Related

- [Project Structure](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/technical/getting-started/project-structure)


## Sitemap

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