Bun · all subjects

api signatures & exact usage

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.

API routes require Bun v1.2.3+

API endpoints using HTTP method handlers in Bun.serve() require Bun version 1.2.3 or later.

import.meta.hot API availability check

You can check if the HMR API is available with `if (import.meta.hot)`, which tree-shakes in production. Calls to HMR APIs are dead-code-eliminated in production builds.

Dead-code elimination requires direct import.meta.hot calls

For dead-code elimination to work, Bun requires HMR APIs to be called without indirection. The full phrase 'import.meta.hot.<API>' must be called directly. Invalid patterns include: assigning `hot` to a variable, assigning `import.meta` to a variable, or passing `import.meta.hot.dispose` to a function. The exception is that `data` can be passed to functions.

import.meta.hot API methods and status

The import.meta.hot API provides the following methods: hot.accept() (✅ implemented - indicate that a hot update can be replaced gracefully), hot.data (✅ implemented - persist data between module evaluations), hot.dispose() (✅ implemented - add a callback function to run when a module is about to be replaced), hot.invalidate() (❌ not implemented), hot.on() (✅ implemented - attach an event listener), hot.off() (✅ implemented - remove an event listener from on), hot.send() (❌ not implemented), hot.prune() (🚧 work in progress - callback is currently never called), hot.decline() (✅ implemented - no-op to match Vite's import.meta.hot).

import.meta.hot.accept() without arguments

When called without arguments, import.meta.hot.accept() indicates that a module can be hot-replaced. This means Bun can replace the module by re-evaluating the file. After a hot update, Bun automatically patches the module's importers. This call creates a hot-reloading boundary for all files that the module imports. Whenever a dependency is saved, the update bubbles up to this module which re-evaluates. Bun then patches files that import this module to import the new version. If only this module is updated, Bun re-evaluates only that file and reuses the state of its dependencies.

import.meta.hot.accept() with callback

When passed a callback, import.meta.hot.accept(newModule => {...}) calls the callback with the new module instead of patching importers. The newModule parameter is undefined when a SyntaxError occurred. This variant works as it does in Vite.

import.meta.hot.accept() with dependency string

import.meta.hot.accept('./foo', newModule => {...}) indicates that a specific dependency can be accepted. When the dependency is updated, Bun calls the callback with the new module.

import.meta.hot.accept() with multiple dependencies

import.meta.hot.accept(['./foo', './bar'], newModules => {...}) accepts an array of dependencies. The callback receives an array where each item corresponds to the updated module or undefined if that module had a syntax error.

import.meta.hot.data carries state between module evaluations

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()). In production, Bun inlines data as {}, so it cannot be used as a state holder. Bun can minify {}.prop ??= value into value in production.

import.meta.hot.dispose() callback timing

import.meta.hot.dispose() attaches an on-dispose callback that Bun calls: 1) just before the module is replaced with another copy (before the next is loaded), and 2) after the module is detached (when all imports to this module are removed). 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() callback behavior

import.meta.hot.prune() attaches an on-prune callback that Bun calls 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 dispose(), it pairs better with accept and data for managing stateful resources. The callback is currently never called (work in progress).

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

import.meta.hot.on(eventName, callback) attaches an event listener for HMR events. import.meta.hot.off(eventName, callback) removes an event listener from on. 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

Built-in HMR events include: bun:beforeUpdate (emitted 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, indicating the development server is offline), 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:*.

Give your agent this brain