Bake Dev Server and HMR

Relevant source files

• bun.lock
• packages/bun-types/bun.d.ts
• packages/bun-types/deprecated.d.ts
• packages/bun-types/devserver.d.ts
• packages/bun-types/fetch.d.ts
• packages/bun-types/globals.d.ts
• packages/bun-types/index.d.ts
• packages/bun-types/overrides.d.ts
• packages/bun-types/package.json
• packages/bun-types/scripts/build.ts
• packages/bun-types/shell.d.ts
• packages/bun-types/test-globals.d.ts
• src/bundler/bundle_v2.zig
• src/css/values/url.zig
• src/js/node/async_hooks.ts
• src/runtime/bake/hmr-module.ts
• test/bake/bake-harness.ts
• test/bake/client-fixture.mjs
• test/bake/dev-and-prod.test.ts
• test/bake/dev/bundle.test.ts
• test/bake/dev/css.test.ts
• test/bake/dev/esm.test.ts
• test/bake/dev/hot.test.ts
• test/bake/dev/react-spa.test.ts
• test/bake/dev/sourcemap.test.ts
• test/bake/dev/stress.test.ts
• test/bundler/expectBundled.ts
• test/cli/hot/hot.test.ts
• test/cli/hot/watch.test.ts
• test/cli/test/process-kill-fixture-sync.ts
• test/cli/test/process-kill-fixture.ts
• test/cli/test/test-timeout-behavior.test.ts
• test/cli/watch/watch.test.ts
• test/expectations.txt
• test/integration/bun-types/bun-types.test.ts
• test/integration/bun-types/fixture/array.ts
• test/integration/bun-types/fixture/broadcast.ts
• test/integration/bun-types/fixture/bun.ts
• test/integration/bun-types/fixture/crypto.ts
• test/integration/bun-types/fixture/env.ts
• test/integration/bun-types/fixture/globals.ts
• test/integration/bun-types/fixture/html.html
• test/integration/bun-types/fixture/http.ts
• test/integration/bun-types/fixture/index.ts
• test/integration/bun-types/fixture/package.json
• test/integration/bun-types/fixture/serve-types.test.ts
• test/integration/bun-types/fixture/serve.ts
• test/integration/bun-types/fixture/spawn.ts
• test/integration/bun-types/fixture/streams.ts
• test/integration/bun-types/fixture/text-encode-decoder.ts
• test/integration/bun-types/fixture/websocket.ts
• test/integration/vite-build/vite-build.test.ts
• test/js/bun/http/bun-serve-static.test.ts
• test/js/bun/http/fetch-file-upload.test.ts
• test/js/node/async_hooks/async_hooks.node.test.ts
• test/regression/issue/5228.test.js

The Bake Development Server is Bun's full-stack development environment. It integrates an incremental bundler, a framework-aware router, and a Hot Module Replacement (HMR) runtime to provide near-instant feedback during development. Unlike traditional dev servers that re-scan or re-bundle large portions of the dependency graph, Bake utilizes a data-oriented incremental graph to ensure that editing a file only triggers a re-bundle of that specific file [src/runtime/bake/DevServer.rs:4-9].

DevServer Architecture

The DevServer is the central orchestrator, typically attached to a Bun.serve instance [src/runtime/bake/DevServer.rs:1-2]. It manages distinct transpilers for the client, server, and SSR environments to ensure correct module resolution and transformation across the full stack [src/runtime/bake/DevServer.rs:129-157].

Core Components

• IncrementalGraph: Manages the dependency tree and tracks file changes to perform minimal rebundling [src/runtime/bake/DevServer.rs:78].
• FrameworkRouter: Discovers routes from the filesystem based on framework-specific configurations, mapping file paths to OpaqueFileId identifiers [src/runtime/bake/DevServer.rs:39].
• RouteBundle: Stores the bundling state, assets, and metadata for every navigatable route [src/runtime/bake/DevServer.rs:160].
• HmrSocket: Manages WebSocket connections to clients for pushing hot updates and receiving error reports [src/runtime/bake/DevServer.rs:50].
• SourceMapStore: Stores and serves source maps for both original files and generated chunks, enabling accurate debugging in the browser [src/runtime/bake/DevServer.rs:162].

Data Flow: File Change to HMR Update

The following diagram illustrates the flow from a filesystem event to a client-side update.

DevServer Update Pipeline

Sources: [src/runtime/bake/DevServer.rs:32-50], [src/runtime/bake/DevServer.rs:129-157], [test/cli/hot/hot.test.ts:132-144]

Incremental Bundling and Linker Integration

Bake uses BundleV2 for its core bundling logic but configures it for incremental operation. It utilizes a FileMap or memory-resident FileSystem to avoid expensive disk I/O during the hot-reload cycle [src/runtime/server/server_body.rs:35-36].

Barrel Import Optimization

Bake implements a "Barrel Optimization" strategy to defer loading unused submodules from pure re-export files. This uses a RequestedExports map to track which specific exports are needed [src/bundler/barrel_imports.zig:12-15]. During development, the DevServer persists barrel_needed_exports across builds to ensure that if a new file imports an existing export from a barrel, the barrel doesn't need to be fully re-parsed [src/bundler/barrel_imports.zig:111-120].

Entity	Role in Code	Location
DevServer	Main orchestrator of the development lifecycle	[src/runtime/bake/DevServer.rs:81]
Transpiler	Handles TS/JSX to JS conversion for server/client/ssr	[src/runtime/bake/DevServer.rs:129-157]
RequestedExports	Tracks all or partial export requests for barrel files	[src/bundler/barrel_imports.zig:12-15]
RouteBundle	Container for a route's bundled code and assets	[src/runtime/bake/DevServer.rs:160]

Sources: [src/runtime/bake/DevServer.rs:1-166], [src/bundler/barrel_imports.zig:1-120], [src/runtime/server/server_body.rs:10-12]

HMR Runtime and Module Lifecycle

Bun's HMR system allows developers to update code without losing application state. The runtime on the client manages a registry of modules and their acceptance status.

Update Logic

When the server sends a hot update, the client-side fixture (e.g., client-fixture.mjs) or the browser runtime performs the following:

1. Module Replacement: New code is evaluated (often via blob: URLs in testing environments) and replaces the previous module entry [test/bake/client-fixture.mjs:149-161].
2. Bubbling: If a module does not self-accept via import.meta.hot.accept(), the update "bubbles" up the dependency graph. If no parent accepts the update, a full page reload is triggered [test/bake/dev/bundle.test.ts:199-202].
3. CSS Hot Reloading: Stylesheets are updated dynamically. If a CSS update contains a syntax error, the DevServer retains the old styles to prevent the UI from breaking entirely [test/bake/dev/css.test.ts:6-12].

HMR Entity Mapping

Sources: [src/runtime/bake/DevServer.rs:81-163], [test/bake/dev/bundle.test.ts:199-202], [test/bake/client-fixture.mjs:87-116]

Error Handling and Overlay

When a build or runtime error occurs, Bake provides a specialized client-side overlay. Build failures, such as syntax errors or resolution failures, are serialized on the server using SerializedFailure and sent to the client to be displayed in the HMR overlay [src/runtime/bake/DevServer.rs:161].

Source Map Integration

The DevServer maintains a SourceMapStore to associate generated code with original source locations [src/runtime/bake/DevServer.rs:162]. This is critical for:

• Stack Trace Remapping: Converting runtime errors in bundled code back to the original TypeScript/JSX source.
• Interactive Debugging: Allowing the browser's DevTools to map the bundled chunks back to the project files.

Asset Management

Assets (images, fonts, etc.) are served via a specialized Assets store [src/runtime/bake/DevServer.rs:52]. When a CSS file references an asset via url(), the dev server automatically tracks this dependency. If the asset on disk changes, the DevServer can trigger a re-fetch or HMR update for the dependent stylesheet [test/bake/dev/css.test.ts:167-188].

Sources: [src/runtime/bake/DevServer.rs:52-163], [test/bake/dev/css.test.ts:167-188], [test/bake/dev/sourcemap.test.ts:1-4]