Bun Hot reloading

Files (1)

• SKILL.md

SKILL.md (first lines)

# Hot reloading

> Hot Module Replacement (HMR) for Bun's development server

Hot Module Replacement (HMR) allows you to update modules in a running application without needing a full page reload. This preserves the application state and improves the development experience.

<Note>HMR is enabled by default when using Bun's full-stack development server.</Note>

## `import.meta.hot` API Reference

Bun implements a client-side HMR API modeled after [Vite's `import.meta.hot` API](https://vite.dev/guide/api-hmr). It can be checked for with `if (import.meta.hot)`, tree-shaking it in production.

```ts title="index.ts" icon="https://mintcdn.com/bun-1dd33a4e/nIz6GtMH5K-dfXeV/icons/typescript.svg?fit=max&auto=format&n=nIz6GtMH5K-dfXeV&q=85&s=5d73d76daf7eb7b158469d8c30d349b0" theme={"theme":{"light":"github-light","dark":"dracula"}}
if (import.meta.hot) {
  // HMR APIs are available.
}
```

However, this check is often not needed as Bun will dead-code-eliminate calls to all of the HMR APIs in production builds.

```ts title="index.ts" icon="https://mintcdn.com/bun-1dd33a4e/nIz6GtMH5K-dfXeV/icons/typescript.svg?fit=max&auto=format&n=nIz6GtMH5K-dfXeV&q=85&s=5d73d76daf7eb7b158469d8c30d349b0" theme={"theme":{"light":"github-light","dark":"dracula"}}
// This entire function call will be removed in production!
import.meta.hot.dispose(() => {
  console.log("dispose");
});
```

<Warning>
  For this to work, Bun forces these APIs to be called without indirection. That means the following do not work:

  ```ts title="index.ts" icon="https://mintcdn.com/bun-1dd33a4e/nIz6GtMH5K-dfXeV/icons/typescript.svg?fit=max&auto=format&n=nIz6GtMH5K-dfXeV&q=85&s=5d73d76daf7eb7b158469d8c30d349b0" theme={"theme":{"light":"github-light","dark":"dracula"}}
  // 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);
  ```
</Warning>

<Note>
  The HMR API is still a work in progress. Some features are missing. HMR can be disabled in `Bun.serve` by setting the development option to `{ hmr: false }`.
</Note>

## API Methods

| Method             | Status | Notes                                                                 |
| ------------------ | ------ | --------------------------------------------------------------------- |
| `hot.accept()`     | ✅      | Indicate that a hot update can be replaced gracefully.                |
| `hot.data`         | ✅      | Persist data between module evaluations.                              |
| `hot.dispose()`    | ✅      | Add a callback function to run when a module is about to be replaced. |
| `hot.invalidate()` | ❌      |                                                                       |
| `hot.on()`         | ✅      | Attach an event listener                                              |
| `hot.off()`        | ✅      | Remove an event listener from `on`.                                   |
| `hot.send()`       | ❌      |                                                                       |
| `hot.prune()`      | 🚧     | NOTE: Callback is currently never called.                             |
| `hot.decline()`    | ✅      | No-op to match Vite's `import.meta.hot`                               |

## import.meta.hot.accept()

The `accept()` method indicates that a module can be hot-replaced. When called without arguments, it indicates that this module can be replaced simply by re-evaluating the file. After a hot update, importers of this module will be automatically patched.

```ts title="index.ts" icon="https://mintcdn.com/bun-1dd33a4e/nIz6GtMH5K-dfXeV/icons/typescript.svg?fit=max&auto=format&n=nIz6GtMH5K-dfXeV&q=85&s=5d73d76daf7eb7b158469d8c30d349b0" theme={"theme":{"light":"github-light","dark":"dracula"}}
// 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. That means whenever `foo.ts` or any of its dependencies are saved, the update will bubble up to `index.ts` will re-evaluate. Files that import `index.ts` will then be patched to import the new version of `getNegativeCount()`. If only `index.ts` is updated, only the one file will be re-evaluated, and the counter in `foo.ts` is reused.

This may be used in combination with `import.meta.hot.data` to transfer state from the previous module to the new one.

<Info>
  When no modules call `import.meta.hot.accept()` (and there isn't React Fast Refresh or a plugin calling it for you),
  the page will reload when the file updates, and a console warning shows which files were invalidated. This warning is
  safe to ignore if it makes more sense to rely on full page reloads.
</Info>

### With callback

When provided one callback, `import.meta.hot.accept` will function how it does in Vite. Instead of patching the importers of this module, it will call the callback with the new module.

```ts title="index.ts" icon="https://mintcdn.com/bun-1dd33a4e/nIz6GtMH5K-dfXeV/icons/typescript.svg?fit=max&auto=format&n=nIz6GtMH5K-dfXeV&q=85&s=5d73d76daf7eb7b158469d8c30d349b0" theme={"theme":{"light":"github-light","dark":"dracula"}}
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);
  }
});
```

<Tip>
  Prefer using `import.meta.hot.accept()` without an argument as it usually makes your code easier to understand.
</Tip>

### Accepting other modules

```ts title="index.ts" icon="https://mintcdn.com/bun-1dd33a4e/nIz6GtMH5K-dfXeV/icons/typescript.svg?fit=max&auto=format&n=nIz6GtMH5K-dfXeV&q=85&s=5d73d76daf7eb7b158469d8c30d349b0" theme={"theme":{"light":"github-light","dark":"dracula"}}
import { count } from "./foo";

From jarle/bun-skills, MIT.

More from jarle/bun-skills