Hot reloading

Hot Module Replacement (HMR) updates modules in a running application without a full page reload, preserving application state.

import.meta.hot API Reference

Bun implements a client-side HMR API modeled after Vite's import.meta.hot API. You can check for it with if (import.meta.hot), which tree-shakes it in production.

if (import.meta.hot) {
  // HMR APIs are available.
}

This check is often unnecessary, since Bun dead-code-eliminates calls to all of the HMR APIs in production builds.

// This entire function call is removed in production.
import.meta.hot.dispose(() => {
  console.log("dispose");
});

// INVALID: Assigning `hot` to a variable
const hot = import.meta.hot;
hot.accept();

// INVALID: Assigning `import.meta` to a variable
const meta = import.meta;
meta.hot.accept();
console.log(meta.hot.data);

// INVALID: Passing to a function
doSomething(import.meta.hot.dispose);

// OK: The full phrase "import.meta.hot.<API>" must be called directly:
import.meta.hot.accept();

// OK: `data` can be passed to functions:
doSomething(import.meta.hot.data);

API Methods

import.meta.hot.accept()

The accept() method indicates that a module can be hot-replaced. Called without arguments, it means this module can be replaced by re-evaluating the file. After a hot update, Bun automatically patches the module's importers.

// index.ts
import { getCount } from "./foo.ts";

console.log("count is ", getCount());

import.meta.hot.accept();

export function getNegativeCount() {
  return -getCount();
}

This creates a hot-reloading boundary for all of the files that index.ts imports. Whenever foo.ts or any of its dependencies are saved, the update bubbles up to index.ts, which re-evaluates. Files that import index.ts are then patched to import the new version of getNegativeCount(). If only index.ts is updated, only that one file is re-evaluated, and the counter in foo.ts is reused.

Combine this with import.meta.hot.data to transfer state from the previous module to the new one.

With callback

When passed a callback, import.meta.hot.accept works as it does in Vite. Instead of patching the importers of this module, it calls the callback with the new module.

export const count = 0;

import.meta.hot.accept(newModule => {
  if (newModule) {
    // newModule is undefined when SyntaxError happened
    console.log("updated: count is now ", newModule.count);
  }
});

Accepting other modules

import { count } from "./foo";

import.meta.hot.accept("./foo", () => {
  if (!newModule) return;

  console.log("updated: count is now ", count);
});

Indicates that a dependency's module can be accepted. When the dependency is updated, Bun calls the callback with the new module.

With multiple dependencies

import.meta.hot.accept(["./foo", "./bar"], newModules => {
  // newModules is an array where each item corresponds to the updated module
  // or undefined if that module had a syntax error
});

This variant accepts an array of dependencies. The callback receives the updated modules, and undefined for any that had errors.

import.meta.hot.data

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 also marks the module as self-accepting (equivalent to calling import.meta.hot.accept()).

import { createRoot } from "react-dom/client";
import { App } from "./app";

const root = (import.meta.hot.data.root ??= createRoot(elem));
root.render(<App />); // re-use an existing root

In production, data is inlined to be {}, meaning it cannot be used as a state holder.

import.meta.hot.dispose()

Attaches an on-dispose callback. This is called:

• Just before the module is replaced with another copy (before the next is loaded)
• After the module is detached (removing all imports to this module, see import.meta.hot.prune())

const sideEffect = setupSideEffect();

import.meta.hot.dispose(() => {
  sideEffect.cleanup();
});

Returning a promise delays module replacement until the module is disposed. All dispose callbacks are called in parallel.

import.meta.hot.prune()

Attaches an on-prune callback. This is called when all imports to this module are removed, but the module was previously loaded.

Use it to clean up resources that were created when the module was loaded. Unlike import.meta.hot.dispose(), it pairs better with accept and data for managing stateful resources. A full example managing a WebSocket:

import { something } from "./something";

// Initialize or re-use a WebSocket connection
export const ws = (import.meta.hot.data.ws ??= new WebSocket(location.origin));

// If the module's import is removed, clean up the WebSocket connection.
import.meta.hot.prune(() => {
  ws.close();
});

import.meta.hot.on() and off()

Use on() and off() to listen for events from the HMR runtime. Event names carry a prefix so that plugins do not conflict with each other.

import.meta.hot.on("bun:beforeUpdate", () => {
  console.log("before a hot update");
});

When a file is replaced, all of its event listeners are automatically removed.

Built-in events