Dev server

The dev server is what next dev starts. Built on top of the production server's BaseServer plus a bundler-specific hot reloader, on-demand entry compilation, and a developer overlay UI.

Class hierarchy

graph TD
    BaseServer[BaseServer<br/>base-server.ts]
    NextNode[NextNodeServer<br/>next-server.ts]
    NextDev[NextDevServer<br/>dev/next-dev-server.ts]

    BaseServer --> NextNode
    NextNode --> NextDev

packages/next/src/server/dev/next-dev-server.ts (~36 KB) extends NextNodeServer and adds:

• On-demand compilation
• Hot reloading
• The dev devtool overlay
• Dev-only diagnostics (e.g., warning if a Server Component imports a client-only module)

Hot reloaders

Three implementations live side-by-side under packages/next/src/server/dev/:

File	Bundler	Size
hot-reloader-turbopack.ts	Turbopack	60 KB
hot-reloader-webpack.ts	webpack	64 KB
hot-reloader-rspack.ts	rspack	8 KB (mostly delegates to webpack flow)

Each implements the NextHotReloader interface defined in hot-reloader-types.ts. The dev server picks one at startup based on the bundler choice (Turbopack default, --webpack, or NEXT_RSPACK=1).

Turbopack hot reloader

hot-reloader-turbopack.ts wraps the napi-rs NextProject from crates/next-api. It:

1. Subscribes to a per-route entry change stream.
2. On each change, asks Turbopack for the new chunks and writes them to the per-page output area.
3. Pushes hot-update messages to connected browsers via the WebSocket in hot-middleware.ts.

webpack hot reloader

hot-reloader-webpack.ts runs webpack in watch mode. Each invalidation rebuilds the affected entries and pushes the standard webpack-hot-middleware messages.

On-demand compilation

packages/next/src/server/dev/on-demand-entry-handler.ts (35 KB) is the heart of dev-server lazy compilation. Instead of building every route up front, the dev server defers each route's compilation until the first request hits it.

sequenceDiagram
    participant Browser
    participant DevServer as NextDevServer
    participant OnDemand as on-demand-entry-handler
    participant Bundler as Hot reloader

    Browser->>DevServer: GET /dashboard
    DevServer->>OnDemand: ensure entry for /dashboard
    OnDemand->>Bundler: compile entry
    Bundler-->>OnDemand: compiled
    OnDemand-->>DevServer: ready
    DevServer-->>Browser: render and respond

The on-demand handler keeps a heat map of recently-used routes and unloads cold ones to keep memory bounded.

Dev devtools overlay

packages/next/src/next-devtools/ implements the in-page overlay that shows compile errors, runtime errors, route info, and a toggle for the dev indicator. The overlay:

• Reads compile errors over the same WebSocket as HMR.
• Renders client-side errors via React error boundaries plus a custom component that pretty-prints stacks.
• Exposes a small MCP server for IDE integrations (see packages/next/src/server/mcp/).

Toggle the dev indicator visibility through the overlay toolbar.

Browser logs

packages/next/src/server/dev/browser-logs/ collects browser console output and forwards it to the terminal so server-side log viewing is unified. Exposed by the dev server via a special endpoint.

Hot middleware

packages/next/src/server/dev/hot-middleware.ts is the WebSocket middleware that pushes HMR messages, error overlays, and refresh signals to connected browsers. It's bundler-agnostic — both webpack and Turbopack use the same protocol.

Static paths worker

For getStaticPaths and generateStaticParams calls during dev, packages/next/src/server/dev/static-paths-worker.ts runs the user's data-fetching function in a child worker, isolating it from the dev server process.

Source maps in dev

Dev-mode error stacks need source maps to point back at the user's source files, not the bundled output. packages/next/src/server/dev/get-source-map-from-file.ts and packages/next/src/server/dev/node-stack-frames.ts resolve source map URLs and rewrite Node stack frames.

The error inspector at packages/next/src/server/patch-error-inspect.ts filters internal frames by default — set __NEXT_SHOW_IGNORE_LISTED=true to disable filtering.

Server actions in dev

Server actions are logged through packages/next/src/server/dev/server-action-logger.ts. The action handler still lives in packages/next/src/server/app-render/action-handler.ts; the dev logger only attaches verbose output.

Log requests

packages/next/src/server/dev/log-requests.ts produces the per-request log lines you see in dev. Each line is keyed by route, status, and duration.

Integration points

• Wraps the same BaseServer as production.
• Drives one of three bundlers via the hot-reloader interface.
• Pushes errors to the dev devtools overlay.
• Exposes a WebSocket endpoint at the same port as the dev HTTP server.

Entry points for modification

• To add a dev-only diagnostic: packages/next/src/server/dev/next-dev-server.ts.
• To change HMR transport: packages/next/src/server/dev/hot-middleware.ts.
• To add a hot-reload event: packages/next/src/server/dev/hot-reloader-types.ts, then implement in each reloader.
• To change the on-demand strategy: packages/next/src/server/dev/on-demand-entry-handler.ts.

Key source files

File	Purpose
packages/next/src/server/dev/next-dev-server.ts	Dev server class
packages/next/src/server/dev/on-demand-entry-handler.ts	Lazy per-route compilation
packages/next/src/server/dev/hot-reloader-types.ts	Hot reloader interface
packages/next/src/server/dev/hot-reloader-turbopack.ts	Turbopack hot reloader
packages/next/src/server/dev/hot-reloader-webpack.ts	webpack hot reloader
packages/next/src/server/dev/hot-reloader-rspack.ts	rspack hot reloader
packages/next/src/server/dev/hot-middleware.ts	WebSocket middleware
packages/next/src/server/dev/log-requests.ts	Per-request log lines
packages/next/src/server/dev/static-paths-worker.ts	Worker for static path generation
packages/next/src/next-devtools/	In-page devtool overlay
packages/next/src/server/patch-error-inspect.ts	Error stack inspection