Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/guides/http/hot.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ sidebarTitle: Hot reload an HTTP server
mode: center
---

The [`--hot`](/runtime/watch-mode#hot-mode) flag runs a file with hot reloading enabled. When any module or file changes, Bun re-runs the file.
The [`--hot`](/runtime/watch-mode#hot-mode) flag runs a file with hot reloading enabled. When that file or a file it imports changes, Bun re-runs it. Bun does not watch files that no module imports, such as `.env`, `bunfig.toml`, and `tsconfig.json`. Restart Bun to apply a change to one of those files.

```sh terminal icon="terminal"
bun --hot run index.ts
Expand Down
21 changes: 21 additions & 0 deletions docs/runtime/module-resolution.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -292,6 +292,27 @@ await Bun.build({
});
```

### Built-in replacements for npm packages

Bun includes its own implementation of a few npm packages. When you import one of the following specifiers, Bun loads the built-in module. Bun does this even when the package is installed in `node_modules`.

| Specifier | Built-in module |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `undici` | `fetch`, `Request`, `Response`, `Headers`, `FormData`, `File`, and `WebSocket` are Bun's own. `request()` calls Bun's `fetch`. |
| `node-fetch` | A wrapper around Bun's `fetch`. `response.body` is a Node.js `Readable` stream, as in `node-fetch`. |
| `isomorphic-fetch` | Bun's `fetch`. |
| `@vercel/fetch` | A wrapper around Bun's `fetch`. |
| `ws`, `ws/lib/websocket` | `WebSocket` and `WebSocketServer`, built on Bun's native WebSocket client and server. |
| `utf-8-validate` | The same native function as `isUtf8()` in `node:buffer`. |
| `abort-controller`, `abort-controller/polyfill` | The global `AbortController` and `AbortSignal`. |
| `next/dist/compiled/undici`, `next/dist/compiled/node-fetch`, `next/dist/compiled/ws` | The same built-in modules as `undici`, `node-fetch`, and `ws`. |

A built-in module does not implement every API of the package it replaces. For example, the built-in `undici` exports `Agent`, `Pool`, `Client`, `ProxyAgent`, and `MockAgent` so that imports succeed. These classes do not manage connections, and `fetch` ignores the `dispatcher` option. `stream()`, `pipeline()`, `connect()`, and `upgrade()` throw an error. If your code needs an API that is missing, [open an issue](https://bun.com/issues).

Bun matches the whole specifier. Any other subpath, such as `undici/package.json`, resolves to the installed package. For a replaced specifier, `require.resolve()` and `import.meta.resolve()` return the name of the built-in module instead of a file path. For example, both `"undici"` and `"next/dist/compiled/undici"` resolve to `"undici"`.

[`bun build`](/bundler) applies the same replacement when the target is `bun`, and leaves the import in the bundle. With `--target=node` or `--target=browser`, `bun build` bundles the copy in `node_modules`.

---

## Path re-mapping
Expand Down
2 changes: 1 addition & 1 deletion docs/runtime/watch-mode.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -122,9 +122,9 @@ bun --hot server.ts
```

```txt
Reloaded 0 times
Reloaded 1 times
Reloaded 2 times
Reloaded 3 times
```

Traditional file watchers like `nodemon` restart the entire process, so HTTP servers and other stateful objects are lost. By contrast, `bun --hot` reflects the updated code without restarting the process.
Expand Down