Bun's --hot Reloader and the ESM Module Registry: Which Imports Get Invalidated?

In Bun 1.x, the distinction between `--watch` and `--hot` is critical to understanding how the module registry behaves. While `--watch` typically restarts the entire process upon file changes, `--hot` attempts to patch the running application by invalidating specific nodes in the dependency graph. ### Cache vs. Memory When a file is edited during a `--hot` session, Bun invalidates the in-memory module record for that specific path. However, it does not necessarily clear the on-disk transpile cache. Bun detects the file change, re-transpiles the edited file, and updates the internal ESM registry. This ensures that the next time the module is required, Bun fetches the latest code without the overhead of a full process restart. ### Transitive Dependents and Evaluation The most common point of confusion is how changes propagate. In the current implementation of hot reloading:

• Leaf modules are re-evaluated when they change.
• Transitive dependents are NOT automatically re-evaluated if they used static ESM imports. Because ESM bindings are resolved at load-time, the parent module retains the reference to the old memory location of the export.
• The entry module is typically re-executed as it serves as the root of the reload cycle.

To force dependents to re-evaluate, you would generally need to use dynamic import() or utilize Bun-specific hot-reload APIs to manually manage state and logic updates. ### Manual Invalidation Currently, there is no supported public API or CLI flag to force the invalidation of a specific module path without restarting the process. The invalidation is driven entirely by the file watcher's discovery of the dependency graph. ### Verification Steps To observe this behavior in your specific Bun version, run this minimal test:

# leaf.js
export let value = 1;

# index.js
import { value } from './leaf.js';
console.log('Static:', value);

Bun.hot.reload(() => {
  console.log('Reloaded:', value);
});
pre>
Run bun --hot index.js. Change value = 2 in leaf.js. You will likely see the static import remains 1 while the reload-triggered logic reflects the new state.