turbopack-dev-server

The HTTP + WebSocket dev server crate. Runs alongside turbopack-core to serve compiled chunks, push HMR updates, and host the Turbopack CLI's dev mode.

Source: turbopack/crates/turbopack-dev-server/src/.

Layout

File	Size	Role
lib.rs	14 KB	DevServer struct + entry
http.rs	11 KB	HTTP request handling
html.rs	9 KB	HTML response building (index + error pages)
update/	—	HMR update streaming over WebSocket
source/	—	ContentSource trait — what a request resolves to
introspect/	—	Debug/introspection endpoints
invalidation.rs	3 KB	Plugs invalidations from turbo-tasks into HMR

Architecture

graph TD
    Browser --> Http[http.rs]
    Http --> Source[ContentSource]
    Source --> Project[turbopack-core /<br/>turbopack-ecmascript /<br/>turbopack-css]
    Project --> Output[OutputAsset]
    Output --> Http
    Http --> Browser

    Browser <--> Ws[update/<br/>WebSocket]
    Ws --> Invalidation[invalidation.rs]
    Invalidation --> TurboTasks[turbo-tasks]
    TurboTasks -. invalidates .-> Output

ContentSource

The ContentSource trait is the dispatch surface. Each path-prefix on the dev server is owned by a ContentSource that decides what to do with a request. Multiple sources compose into a tree.

For Next.js, the dev server uses content sources that map:

• /_next/static/* → static-asset source over the project's chunk output.
• /_next/data/* → JSON data source.
• /* → the compiled HTML for the route.
• WebSocket /_next/webpack-hmr → the HMR update source.

HMR updates

update/ defines the over-the-wire HMR protocol (paired with turbopack-ecmascript-hmr-protocol). On invalidation, the framework pushes:

1. A started message for each affected entry.
2. A diff between old and new chunks.
3. A finished message.

The browser's runtime applies the diff and triggers a fast refresh.

HTML response

html.rs builds the per-route HTML response. For the standalone Turbopack CLI, this is a developer's index.html-style document with the chunk loader bootstrap. For Next.js, the HTML is produced by the Node runtime — the dev server only serves chunks.

Introspection

introspect/ exposes runtime info about the turbo-tasks graph. Useful for debugging "why was this rebuilt?" — visit /__introspect__/... paths to see a task's inputs and dependents.

Integration

In Next.js dev (pnpm next dev), the JS dev server (packages/next/src/server/dev/next-dev-server.ts) creates a NextProject via crates/next-api, then drives a turbopack-dev-server instance to serve chunks. The JS server still owns HTTP routing for app routes — the Turbopack dev server just handles /_next/static and the HMR socket.

For the standalone Turbopack CLI (turbopack/crates/turbopack-cli/), turbopack-dev-server is the whole thing — it owns HTTP routing too.

Key source files

File	Purpose
turbopack/crates/turbopack-dev-server/src/lib.rs	DevServer struct
turbopack/crates/turbopack-dev-server/src/http.rs	HTTP request handling
turbopack/crates/turbopack-dev-server/src/html.rs	HTML response building
turbopack/crates/turbopack-dev-server/src/update/	WebSocket HMR updates
turbopack/crates/turbopack-dev-server/src/source/	ContentSource trait
turbopack/crates/turbopack-dev-server/src/introspect/	Runtime introspection
turbopack/crates/turbopack-dev-server/src/invalidation.rs	turbo-tasks → HMR plumbing