Hot Module Reloading in React with Bun
Run `bun dev` to start the app in development mode with hot reloading enabled for both the API server and React app.
bundler behavior & hot module reload
13 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
HMR enabled by default in Bun development server
Hot Module Replacement (HMR) is enabled by default when using Bun's full-stack development server. HMR updates modules in a running application without a full page reload, preserving application state.
import.meta.hot API available in Bun
Bun implements a client-side HMR API modeled after Vite's import.meta.hot API. You can check for its availability with if (import.meta.hot). This check tree-shakes it in production, and Bun dead-code-eliminates calls to all HMR APIs in production builds.
import.meta.hot dead-code elimination requires direct API calls
For dead-code elimination to work, Bun forces HMR APIs to be called without indirection. Invalid patterns include: assigning hot to a variable (const hot = import.meta.hot; hot.accept()), assigning import.meta to a variable, or passing HMR methods to functions. Valid usage requires the full phrase "import.meta.hot.<API>" to be called directly, except import.meta.hot.data can be passed to functions.
Disable HMR in Bun.serve with development option
To disable HMR in Bun.serve, set the development option to { hmr: false }. The HMR API is still a work in progress and some features are missing.
import.meta.hot.accept() API method
The accept() method indicates that a module can be hot-replaced. Called without arguments, it means Bun can replace this module by re-evaluating the file. After a hot update, Bun automatically patches the module's importers. When passed a callback, it calls the callback with the new module instead of patching importers. Can accept a single dependency string or array of dependency strings, passing the updated modules to the callback.
import.meta.hot.data persists state across hot replacements
import.meta.hot.data carries state from the previous version of a module to the new one across a hot replacement. Writing to import.meta.hot.data marks the module as self-accepting, equivalent to calling import.meta.hot.accept(). In production, Bun inlines data as {}, so it cannot be used as a state holder. The pattern import.meta.hot.data.prop ??= value can be minified to value in production.
import.meta.hot.dispose() attaches cleanup callback
import.meta.hot.dispose() attaches an on-dispose callback that Bun calls just before the module is replaced with another copy, or after the module is detached by removing all imports. Returning a promise delays module replacement until the module is disposed. Bun calls all dispose callbacks in parallel. Bun does not call this callback on route navigation or when the browser tab closes.
import.meta.hot.prune() manages resources when imports are removed
import.meta.hot.prune() attaches an on-prune callback that Bun calls when all imports to a module are removed but the module was previously loaded. Use it to clean up resources created when the module was loaded. Unlike import.meta.hot.dispose(), it pairs better with accept and data for managing stateful resources. The callback is currently never called as this API is marked as work in progress.
import.meta.hot.on() and off() event listeners
Use import.meta.hot.on() and import.meta.hot.off() to listen for events from the HMR runtime. Event names carry a prefix so plugins do not conflict with each other. When a file is replaced, Bun automatically removes all of its event listeners.
Built-in HMR events in Bun
Bun emits the following HMR events: bun:beforeUpdate (before a hot update is applied), bun:afterUpdate (after a hot update is applied), bun:beforeFullReload (before a full page reload happens), bun:beforePrune (before prune callbacks are called), bun:invalidate (when a module is invalidated with import.meta.hot.invalidate()), bun:error (when a build or runtime error occurs), bun:ws:disconnect (when the HMR WebSocket connection is lost), bun:ws:connect (when the HMR WebSocket connects or re-connects). For compatibility with Vite, these events are also available with the vite:* prefix instead of bun:*.
HMR API method status table
HMR API method status: hot.accept() ✅, hot.data ✅, hot.dispose() ✅, hot.invalidate() ❌, hot.on() ✅, hot.off() ✅, hot.send() ❌, hot.prune() 🚧 (callback is currently never called), hot.decline() ✅ (no-op to match Vite).
Full page reload when no modules accept hot updates
When no modules call import.meta.hot.accept() and there is no React Fast Refresh or a plugin calling it, the page reloads when the file updates. A console warning shows which files were invalidated.