next

Purpose

The next package is the Next.js framework itself. Every npm install next brings in this package, which contains the CLI binary (next), the production server (next start), the dev server (next dev), the build pipeline (next build), the App Router and Pages Router runtimes, and 141 vendored third-party packages.

Source: packages/next/src/. Compiled output: packages/next/dist/ (mirrors src/). Package manifest: packages/next/package.json. Version at this commit: 16.3.0-canary.5.

Directory layout

packages/next/
├── src/
│   ├── api/                    # Public re-exports (next/headers, next/cache, ...)
│   ├── bin/                    # CLI binary entry
│   ├── build/                  # Build pipeline (~150 files, 4.4k LOC index.ts)
│   ├── bundles/                # Pre-bundled runtime entries
│   ├── cli/                    # Per-command CLI scripts
│   ├── client/                 # Client-side runtime (App Router + Pages Router)
│   ├── compiled/               # 141 vendored npm packages
│   ├── diagnostics/            # Dev-mode diagnostic messages
│   ├── experimental/           # Experimental APIs
│   ├── export/                 # Static export pipeline
│   ├── lib/                    # Generic helpers
│   ├── next-devtools/          # In-page devtool overlay
│   ├── pages/                  # Pages Router built-in pages (_app, _document, _error)
│   ├── server/                 # Server runtime (most code)
│   ├── shared/                 # Code used by both client and server
│   ├── telemetry/              # Anonymous telemetry
│   ├── trace/                  # Internal OpenTelemetry tracing
│   └── types.ts                # Public type entry
├── dist/                       # Compiled (mirrors src/)
├── compat/                     # Node legacy compatibility shims
├── taskfile.js                 # Build orchestration
└── package.json

The publication shape exposes individual entries as files at the package root (next/app, next/cache, next/font/*, next/image, next/link, next/server, etc.). These are thin re-exports that point into dist/.

Public entry points

These are the next/* import surfaces user code consumes:

Import	Source
next/link	packages/next/src/client/link.tsx
next/image	packages/next/src/client/image-component.tsx
next/script	packages/next/src/client/script.tsx
next/form	packages/next/src/client/form.tsx
next/router (Pages)	packages/next/src/client/router.ts
next/navigation (App)	packages/next/src/client/components/navigation.ts
next/headers	packages/next/src/server/request/headers.ts (under server/request/)
next/cookies	packages/next/src/server/request/cookies.ts
next/cache	packages/next/src/api/cache.ts
next/server	packages/next/src/server/web/exports/
next/og	packages/next/src/server/og/
next/font/google, local	packages/font/

The *.d.ts shims at the package root (e.g. app.d.ts, cache.d.ts, link.d.ts) exist so TypeScript users can import these without explicit type packages.

CLI

graph LR
    Bin[bin/next<br/>shebang script] --> Dispatcher[lib/commands.ts<br/>arg parser]
    Dispatcher --> Dev[cli/next-dev.ts]
    Dispatcher --> Build[cli/next-build.ts]
    Dispatcher --> Start[cli/next-start.ts]
    Dispatcher --> Export[cli/next-export.ts]
    Dispatcher --> Info[cli/next-info.ts]
    Dispatcher --> Telemetry[cli/next-telemetry.ts]
    Dispatcher --> Test[cli/next-test.ts]
    Dispatcher --> Typegen[cli/next-typegen.ts]
    Dispatcher --> Upgrade[cli/next-upgrade.ts]
    Dispatcher --> Analyze[cli/next-analyze.ts]

Each CLI file under packages/next/src/cli/ exports a nextX(argv) function. next-dev.ts is the largest at 18.6 KB; it spins up the dev server, sets up signal handlers, and prints the start banner.

Adapter API

The directory packages/next/src/build/adapter/ defines the contract between the framework and hosting platforms. Vercel implements this externally; other platforms can target the same surface to integrate their build output.

The main entry is packages/next/src/build/adapter/build-complete.ts (2,215 lines) — it wraps a finished build and converts the output into the platform's deployment shape (function bundles, edge bundles, image config, headers, redirects, rewrites). The adapter receives the route inventory, manifest data, and trace files.

Vendored third-party packages

packages/next/src/compiled/ contains 141 third-party packages that have been pre-bundled into the framework. This isolates user node_modules from the framework's own dependency choices and lets the framework upgrade dependencies without breaking user installs.

The vendoring is driven by taskfile.js compile. A few highlights:

• All of webpack 5 (packages/next/src/compiled/webpack/)
• The complete Babel toolchain
• The OpenTelemetry SDK family
• react-server-dom-webpack and react-server-dom-turbopack
• postcss, browserslist, caniuse-lite
• @modelcontextprotocol/sdk (for the dev MCP server)

When the framework needs one of these, it imports from next/dist/compiled/<name>.

Build entry points

• Dev server: src/cli/next-dev.ts → src/server/dev/next-dev-server.ts
• Production server: src/cli/next-start.ts → src/server/next-server.ts
• Build: src/cli/next-build.ts → src/build/index.ts

Per-subsystem deep dives

The framework is large enough that each major subsystem gets its own page under systems/:

• App Router
• Pages Router
• Server runtime
• Build pipeline
• Dev server
• Image optimization
• Server actions
• Middleware and edge
• Caching

Key source files

File	Purpose
packages/next/src/server/next-server.ts	Production Node.js server
packages/next/src/server/base-server.ts	Shared logic between Node and Edge servers
packages/next/src/server/dev/next-dev-server.ts	Dev server with HMR
packages/next/src/server/lib/router-server.ts	First request entry point
packages/next/src/server/app-render/app-render.tsx	App Router renderer
packages/next/src/server/render.tsx	Pages Router renderer
packages/next/src/build/index.ts	Build orchestrator
packages/next/src/build/webpack-config.ts	webpack configuration
packages/next/src/build/define-env.ts	Build-time env injection
packages/next/src/server/config-shared.ts	Config types and defaults
packages/next/src/server/config-schema.ts	Config zod schema
packages/next/src/server/config.ts	Config loader
packages/next/src/client/components/app-router.tsx	Client App Router
packages/next/src/client/router.ts	Client Pages Router (legacy)
packages/next/taskfile.js	Build pipeline (taskr)