Bake Dev Server and HMR

Relevant source files

• src/runtime/bake/DevServerSourceProvider.h
• 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/react-spa.test.ts
• test/bake/dev/server-sourcemap.test.ts
• test/bake/dev/sourcemap.test.ts
• test/bake/dev/stress.test.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/js/bun/http/fetch-file-upload.test.ts

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) system to provide near-instant feedback. 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 affected modules.

DevServer Architecture

The DevServer is the central orchestrator, typically attached to a Bun.serve instance test/js/bun/http/fetch-file-upload.test.ts10-12 It manages distinct transpilers for the client, server, and SSR environments to ensure correct module resolution and transformation across the full stack test/bake/bake-harness.ts58-71

Core Components

• IncrementalGraph: Manages the dependency tree and tracks file changes to perform minimal rebundling.
• FrameworkRouter: Discovers routes from the filesystem based on framework-specific configurations, such as nextjs-pages style routing test/bake/bake-harness.ts59-65
• HmrSocket: Manages WebSocket connections to clients for pushing hot updates. The client identifies this via messages like [Bun] Live-reloading socket connected test/bake/bake-harness.ts186
• SourceMapStore: Stores and serves source maps for original files and generated chunks, supporting both client-side and server-side stack trace remapping test/bake/dev/sourcemap.test.ts1-7

Data Flow: File Change to HMR Update

The following diagram illustrates the flow from a filesystem event to a client-side update, involving the Dev test harness and the Subprocess that runs the actual server.

DevServer Update Pipeline

Sources: test/bake/bake-harness.ts205-220 test/bake/client-fixture.mjs92-109 test/cli/hot/hot.test.ts10-26

Incremental Bundling and Linker Integration

Bake uses the BundleV2 infrastructure but configures it for incremental operation. It utilizes memory-resident state to avoid expensive disk I/O during the hot-reload cycle.

Module Boundaries and Resolution

Bake handles complex resolution scenarios, such as when a file is imported before it exists on disk. The dev server tracks these "missing" dependencies and automatically triggers a reload once the file is created test/bake/dev/bundle.test.ts79-101 It also respects environment-specific resolution conditions like development vs production defined in package.json test/bake/dev/bundle.test.ts53-78

Entity	Role in Code	Location
Dev	Test harness class for orchestrating dev server tests	test/bake/bake-harness.ts205
Framework	Configuration for router types and server component boundaries	test/bake/bake-harness.ts58
client-fixture.mjs	Node.js based runner using happy-dom to simulate a browser client	test/bake/client-fixture.mjs1-4
driveErrorReloadCycle	Helper to parse stderr and drive the reload cycle for failing code	test/cli/hot/hot.test.ts19-28

Sources: test/bake/bake-harness.ts58-205 test/bake/dev/bundle.test.ts1-101 test/cli/hot/hot.test.ts19-28

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

1. Module Replacement: New code is evaluated and replaces the previous module entry. If import.meta.hot.accept() is present, the module is marked as self-accepting test/bake/dev-and-prod.test.ts5-10
2. Bubbling: If a module does not self-accept, the update "bubbles" up. If it reaches the root without being accepted, a full page reload is triggered test/bake/dev/bundle.test.ts199-202
3. CSS Hot Reloading: Stylesheets are updated dynamically. If a CSS update contains a syntax error, the server reports it but the client keeps the old styles to prevent a broken UI test/bake/dev/css.test.ts6-12

HMR Code Entity Mapping

Sources: test/bake/bake-harness.ts205-222 test/bake/client-fixture.mjs133-143 test/bake/dev/bundle.test.ts169-170

Error Handling and Source Maps

When a build or runtime error occurs, Bake provides specialized reporting. Build failures (syntax errors, resolution failures) are sent to the client to be displayed in an overlay test/bake/dev/css.test.ts209-240

Server-Side Source Maps

Bun supports source maps for server-side code (SSR). This ensures that stack traces for errors occurring in server components or routes point back to the original .tsx or .ts files rather than the transpiled output test/bake/dev/server-sourcemap.test.ts5-26 The system maintains correctness even across repeated HMR updates by re-registering source providers test/bake/dev/server-sourcemap.test.ts152-157

Asset Management and CSS

Assets like images referenced in CSS via url() are tracked. If bun.png is updated, the dev server detects the change and triggers an HMR update for the dependent styles.css test/bake/dev/css.test.ts167-188 Circular CSS imports are also handled correctly during hot reloads test/bake/dev/css.test.ts256-265

The internal_bake_dev Format

The internal_bake_dev format is a specialized output used for client-side bundles in development. It is optimized for the HMR runtime's ability to "patch" existing modules.

• Hot Chunks: When a file changes, the server generates a "hot chunk" containing only the updated module and its metadata test/bake/dev/sourcemap.test.ts56-59
• Blob URL Loading: The client-side runtime often loads these chunks by creating Blob URLs and appending <script> tags, which are emulated in tests via URL.createObjectURL test/bake/client-fixture.mjs122-130
• Live Bindings: The format ensures that ESM live bindings are preserved so that if an exported variable changes, all importers see the new value immediately test/bake/dev/bundle.test.ts5-23

Sources: test/bake/client-fixture.mjs122-130 test/bake/dev/sourcemap.test.ts56-59 test/bake/dev/bundle.test.ts5-23