Architecture Overview
Server Runtime
Rendering Pipeline
Client Navigation
Caching and Export
Development Tools
Build and Configuration
Ecosystem Packages
Testing Infrastructure
How It Works
The following files were used as context for generating this wiki page:
The Next.js Command-Line Interface (CLI) serves as the primary orchestration and entry point for building, developing, serving, and diagnosing Next.js applications. Architected around Commander.js within packages/next/src/bin/next.ts, the CLI defines root commands that map user flags and positional arguments to asynchronous execution handlers. These handlers bootstrap runtime configurations, manage child process lifecycles, and interface directly with underlying compiler pipelines such as Webpack and Turbopack.
Sources: packages/next/src/bin/next.ts:137-155
By decoupling command-line parsing from domain logic, the CLI architecture enforces strict separation between user-facing options and core server infrastructure. Commands validate project root directories, inject environment variables (such as __NEXT_VERSION and NODE_OPTIONS), and capture session-level telemetry or diagnostic profiles (.next-profiles/). Adjacent tooling—including next-codemod, create-next-app, and internal trace query systems—leverage this same command routing structure to offer developers a unified terminal experience across workspace boundaries.
Sources: packages/next/src/bin/next.ts:296-402
The Next.js binary entry point (packages/next/src/bin/next.ts) initializes a NextRootCommand instance configured with standard metadata, help formatting, and version flags. When executed, Commander evaluates process.argv and dispatches control to the registered command action handler.
Sources: packages/next/src/bin/next.ts:137-156
next dev)The next dev command starts Next.js in development mode with hot-code reloading, error reporting, and watcher orchestration. Defined as the default command in packages/next/src/bin/next.ts, it accepts an optional [directory] argument and a broad set of configuration options. When nextDev executes, it performs bundler resolution via parseBundlerArgs(options), verifies the project root via fileExists(), sets up CPU profiling directories, and registers signal handlers (SIGINT, SIGTERM) to flush telemetry via eventCliSessionStopped() and upload traces.
Sources: packages/next/src/cli/next-dev.ts:45-189, packages/next/src/cli/next-dev.ts:204-242
Note
If the development server is restarted within 90,000 ms (RAGE_RESTART_THRESHOLD_MS), the CLI marks the session span attribute 'rage-restart' as true for telemetry analysis.
Sources: packages/next/src/cli/next-dev.ts:81-83
next build)The next build command compiles the application for production deployment. Implemented in packages/next/src/cli/next-build.ts, it establishes process titles, configures signal handlers for CPU profile dumping on termination, and validates bundler compatibility. When invoked, nextBuild initializes environment options, validates project root existence via existsSync(dir), and parses selective build path patterns when --debug-build-paths is provided.
Sources: packages/next/src/cli/next-build.ts:39-170
next start)The next start command launches the Next.js production server for a pre-compiled application. Implemented in packages/next/src/cli/next-start.ts, it enforces start-time environment contracts and manages inspector attachments through strict sequencing: populating NEXT_PRIVATE_START_TIME, validating port reservation via isPortIsReserved(), opening the Node inspector via inspector.open(), attaching CPU profile signal handlers, and invoking startServer().
Sources: packages/next/src/cli/next-start.ts:6-91
Warning
Running next start without executing next build first will fail because production manifests (such as routes-manifest.json and build artifacts) will be missing from the .next directory.
Sources: packages/next/src/cli/next-start.ts:42-90
next info)The next info command collects and outputs environment diagnostics, binary versions, relevant package versions, and Next.js configuration properties to aid in bug reporting. Implemented in packages/next/src/cli/next-info.ts, it gathers system stats asynchronously across operating system properties, package manager binaries, package versions, and configuration outputs.
Sources: packages/next/src/cli/next-info.ts:55-169
os module.
Sources: packages/next/src/cli/next-info.ts:148-153next, eslint-config-next, react, react-dom, typescript, next-rspack).
Sources: packages/next/src/cli/next-info.ts:136-160-/package/next/dist-tags) to compare installed release against latest/canary versions using parseVersionInfo() and getStaleness().
Sources: packages/next/src/cli/next-info.ts:104-120The Next.js CLI includes internal diagnostic commands for analyzing static route bundle sizes (next internal static-routes-info) and querying active Turbopack trace servers (next internal query-trace). Static route analysis partitions route files into 6 disjoint categories to prevent double-counting across pages and app router outputs.
Sources: packages/next/src/cli/internal/static-routes-info.ts:2-79
The query-trace CLI client communicates with a running Turbopack trace server via its Model Context Protocol (MCP) endpoint (http://127.0.0.1:{port}/mcp).