bun-types 1.1.37-canary.20241124T140524 → 1.1.37-canary.20241125T140601

package/docs/runtime/debugger.md

@@ -0,0 +1,325 @@
+---
+name: Debugging
+---
+
+Bun speaks the [WebKit Inspector Protocol](https://github.com/oven-sh/bun/blob/main/packages/bun-types/jsc.d.ts), so you can debug your code with an interactive debugger. For demonstration purposes, consider the following simple web server.
+
+## Debugging JavaScript and TypeScript
+
+```ts#server.ts
+Bun.serve({
+  fetch(req){
+    console.log(req.url);
+    return new Response("Hello, world!");
+  }
+})
+```
+
+### `--inspect`
+
+To enable debugging when running code with Bun, use the `--inspect` flag. This automatically starts a WebSocket server on an available port that can be used to introspect the running Bun process.
+
+```sh
+$ bun --inspect server.ts
+------------------ Bun Inspector ------------------
+Listening at:
+  ws://localhost:6499/0tqxs9exrgrm
+
+Inspect in browser:
+  https://debug.bun.sh/#localhost:6499/0tqxs9exrgrm
+------------------ Bun Inspector ------------------
+```
+
+### `--inspect-brk`
+
+The `--inspect-brk` flag behaves identically to `--inspect`, except it automatically injects a breakpoint at the first line of the executed script. This is useful for debugging scripts that run quickly and exit immediately.
+
+### `--inspect-wait`
+
+The `--inspect-wait` flag behaves identically to `--inspect`, except the code will not execute until a debugger has attached to the running process.
+
+### Setting a port or URL for the debugger
+
+Regardless of which flag you use, you can optionally specify a port number, URL prefix, or both.
+
+```sh
+$ bun --inspect=4000 server.ts
+$ bun --inspect=localhost:4000 server.ts
+$ bun --inspect=localhost:4000/prefix server.ts
+```
+
+## Debuggers
+
+Various debugging tools can connect to this server to provide an interactive debugging experience.
+
+### `debug.bun.sh`
+
+Bun hosts a web-based debugger at [debug.bun.sh](https://debug.bun.sh). It is a modified version of WebKit's [Web Inspector Interface](https://webkit.org/web-inspector/web-inspector-interface/), which will look familiar to Safari users.
+
+Open the provided `debug.bun.sh` URL in your browser to start a debugging session. From this interface, you'll be able to view the source code of the running file, view and set breakpoints, and execute code with the built-in console.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/e6a976a8-80cc-4394-8925-539025cc025d" alt="Screenshot of Bun debugger, Console tab" /%}
+
+Let's set a breakpoint. Navigate to the Sources tab; you should see the code from earlier. Click on the line number `3` to set a breakpoint on our `console.log(req.url)` statement.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/3b69c7e9-25ff-4f9d-acc4-caa736862935" alt="screenshot of Bun debugger" /%}
+
+Then visit [`http://localhost:3000`](http://localhost:3000) in your web browser. This will send an HTTP request to our `localhost` web server. It will seem like the page isn't loading. Why? Because the program has paused execution at the breakpoint we set earlier.
+
+Note how the UI has changed.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/8b565e58-5445-4061-9bc4-f41090dfe769" alt="screenshot of Bun debugger" /%}
+
+At this point there's a lot we can do to introspect the current execution environment. We can use the console at the bottom to run arbitrary code in the context of the program, with full access to the variables in scope at our breakpoint.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/f4312b76-48ba-4a7d-b3b6-6205968ac681" /%}
+
+On the right side of the Sources pane, we can see all local variables currently in scope, and drill down to see their properties and methods. Here, we're inspecting the `req` variable.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/63d7f843-5180-489c-aa94-87c486e68646" /%}
+
+In the upper left of the Sources pane, we can control the execution of the program.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/41b76deb-7371-4461-9d5d-81b5a6d2f7a4" /%}
+
+Here's a cheat sheet explaining the functions of the control flow buttons.
+
+- _Continue script execution_ — continue running the program until the next breakpoint or exception.
+- _Step over_ — The program will continue to the next line.
+- _Step into_ — If the current statement contains a function call, the debugger will "step into" the called function.
+- _Step out_ — If the current statement is a function call, the debugger will finish executing the call, then "step out" of the function to the location where it was called.
+
+{% image src="https://github-production-user-asset-6210df.s3.amazonaws.com/3084745/261510346-6a94441c-75d3-413a-99a7-efa62365f83d.png" /%}
+
+### Visual Studio Code Debugger
+
+Experimental support for debugging Bun scripts is available in Visual Studio Code. To use it, you'll need to install the [Bun VSCode extension](https://bun.sh/guides/runtime/vscode-debugger).
+
+## Debugging Network Requests
+
+The `BUN_CONFIG_VERBOSE_FETCH` environment variable lets you log network requests made with `fetch()` or `node:http` automatically.
+
+| Value   | Description                        |
+| ------- | ---------------------------------- |
+| `curl`  | Print requests as `curl` commands. |
+| `true`  | Print request & response info      |
+| `false` | Don't print anything. Default      |
+
+### Print fetch & node:http requests as curl commands
+
+Bun also supports printing `fetch()` and `node:http` network requests as `curl` commands by setting the environment variable `BUN_CONFIG_VERBOSE_FETCH` to `curl`.
+
+```ts
+process.env.BUN_CONFIG_VERBOSE_FETCH = "curl";
+
+await fetch("https://example.com", {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({ foo: "bar" }),
+});
+```
+
+This prints the `fetch` request as a single-line `curl` command to let you copy-paste into your terminal to replicate the request.
+
+```sh
+[fetch] $ curl --http1.1 "https://example.com/" -X POST -H "content-type: application/json" -H "Connection: keep-alive" -H "User-Agent: Bun/1.1.14" -H "Accept: */*" -H "Host: example.com" -H "Accept-Encoding: gzip, deflate, br" --compressed -H "Content-Length: 13" --data-raw "{\"foo\":\"bar\"}"
+[fetch] > HTTP/1.1 POST https://example.com/
+[fetch] > content-type: application/json
+[fetch] > Connection: keep-alive
+[fetch] > User-Agent: Bun/1.1.14
+[fetch] > Accept: */*
+[fetch] > Host: example.com
+[fetch] > Accept-Encoding: gzip, deflate, br
+[fetch] > Content-Length: 13
+
+[fetch] < 200 OK
+[fetch] < Accept-Ranges: bytes
+[fetch] < Cache-Control: max-age=604800
+[fetch] < Content-Type: text/html; charset=UTF-8
+[fetch] < Date: Tue, 18 Jun 2024 05:12:07 GMT
+[fetch] < Etag: "3147526947"
+[fetch] < Expires: Tue, 25 Jun 2024 05:12:07 GMT
+[fetch] < Last-Modified: Thu, 17 Oct 2019 07:18:26 GMT
+[fetch] < Server: EOS (vny/044F)
+[fetch] < Content-Length: 1256
+```
+
+The lines with `[fetch] >` are the request from your local code, and the lines with `[fetch] <` are the response from the remote server.
+
+The `BUN_CONFIG_VERBOSE_FETCH` environment variable is supported in both `fetch()` and `node:http` requests, so it should just work.
+
+To print without the `curl` command, set `BUN_CONFIG_VERBOSE_FETCH` to `true`.
+
+```ts
+process.env.BUN_CONFIG_VERBOSE_FETCH = "true";
+
+await fetch("https://example.com", {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({ foo: "bar" }),
+});
+```
+
+This prints the following to the console:
+
+```sh
+[fetch] > HTTP/1.1 POST https://example.com/
+[fetch] > content-type: application/json
+[fetch] > Connection: keep-alive
+[fetch] > User-Agent: Bun/1.1.14
+[fetch] > Accept: */*
+[fetch] > Host: example.com
+[fetch] > Accept-Encoding: gzip, deflate, br
+[fetch] > Content-Length: 13
+
+[fetch] < 200 OK
+[fetch] < Accept-Ranges: bytes
+[fetch] < Cache-Control: max-age=604800
+[fetch] < Content-Type: text/html; charset=UTF-8
+[fetch] < Date: Tue, 18 Jun 2024 05:12:07 GMT
+[fetch] < Etag: "3147526947"
+[fetch] < Expires: Tue, 25 Jun 2024 05:12:07 GMT
+[fetch] < Last-Modified: Thu, 17 Oct 2019 07:18:26 GMT
+[fetch] < Server: EOS (vny/044F)
+[fetch] < Content-Length: 1256
+```
+
+## Stacktraces & sourcemaps
+
+Bun transpiles every file, which sounds like it would mean that the stack traces you see in the console would unhelpfully point to the transpiled output. To address this, Bun automatically generates and serves sourcemapped files for every file it transpiles. When you see a stack trace in the console, you can click on the file path and be taken to the original source code, even though it was written in TypeScript or JSX, or has some other transformation applied.
+
+<!-- TODO: uncomment once v1.1.13 regression is fixed (cc @paperdave) -->
+<!-- In Bun, each `Error` object gets four additional properties:
+
+- `line` — the source-mapped line number. This number points to the input source code, not the transpiled output.
+- `column` — the source-mapped column number. This number points to the input source code, not the transpiled output.
+- `originalColumn` — the column number pointing to transpiled source code, without sourcemaps. This number comes from JavaScriptCore.
+- `originalLine` — the line number pointing to transpiled source code, without sourcemaps. This number comes from JavaScriptCore.
+
+These properties are populated lazily when `error.stack` is accessed. -->
+
+Bun automatically loads sourcemaps both at runtime when transpiling files on-demand, and when using `bun build` to precompile files ahead of time.
+
+### Syntax-highlighted source code preview
+
+To help with debugging, Bun automatically prints a small source-code preview when an unhandled exception or rejection occurs. You can simulate this behavior by calling `Bun.inspect(error)`:
+
+```ts
+// Create an error
+const err = new Error("Something went wrong");
+console.log(Bun.inspect(err, { colors: true }));
+```
+
+This prints a syntax-highlighted preview of the source code where the error occurred, along with the error message and stack trace.
+
+```js
+1 | // Create an error
+2 | const err = new Error("Something went wrong");
+                ^
+error: Something went wrong
+      at file.js:2:13
+```
+
+### V8 Stack Traces
+
+Bun uses JavaScriptCore as it's engine, but much of the Node.js ecosystem & npm expects V8. JavaScript engines differ in `error.stack` formatting. Bun intends to be a drop-in replacement for Node.js, and that means it's our job to make sure that even though the engine is different, the stack traces are as similar as possible.
+
+That's why when you log `error.stack` in Bun, the formatting of `error.stack` is the same as in Node.js's V8 engine. This is especially useful when you're using libraries that expect V8 stack traces.
+
+#### V8 Stack Trace API
+
+Bun implements the [V8 Stack Trace API](https://v8.dev/docs/stack-trace-api), which is a set of functions that allow you to manipulate stack traces.
+
+##### Error.prepareStackTrace
+
+The `Error.prepareStackTrace` function is a global function that lets you customize the stack trace output. This function is called with the error object and an array of `CallSite` objects and lets you return a custom stack trace.
+
+```ts
+Error.prepareStackTrace = (err, stack) => {
+  return stack.map(callSite => {
+    return callSite.getFileName();
+  });
+};
+
+const err = new Error("Something went wrong");
+console.log(err.stack);
+// [ "error.js" ]
+```
+
+The `CallSite` object has the following methods:
+
+| Method                     | Returns                                               |
+| -------------------------- | ----------------------------------------------------- |
+| `getThis`                  | `this` value of the function call                     |
+| `getTypeName`              | typeof `this`                                         |
+| `getFunction`              | function object                                       |
+| `getFunctionName`          | function name as a string                             |
+| `getMethodName`            | method name as a string                               |
+| `getFileName`              | file name or URL                                      |
+| `getLineNumber`            | line number                                           |
+| `getColumnNumber`          | column number                                         |
+| `getEvalOrigin`            | `undefined`                                           |
+| `getScriptNameOrSourceURL` | source URL                                            |
+| `isToplevel`               | returns `true` if the function is in the global scope |
+| `isEval`                   | returns `true` if the function is an `eval` call      |
+| `isNative`                 | returns `true` if the function is native              |
+| `isConstructor`            | returns `true` if the function is a constructor       |
+| `isAsync`                  | returns `true` if the function is `async`             |
+| `isPromiseAll`             | Not implemented yet.                                  |
+| `getPromiseIndex`          | Not implemented yet.                                  |
+| `toString`                 | returns a string representation of the call site      |
+
+In some cases, the `Function` object may have already been garbage collected, so some of these methods may return `undefined`.
+
+##### Error.captureStackTrace(error, startFn)
+
+The `Error.captureStackTrace` function lets you capture a stack trace at a specific point in your code, rather than at the point where the error was thrown.
+
+This can be helpful when you have callbacks or asynchronous code that makes it difficult to determine where an error originated. The 2nd argument to `Error.captureStackTrace` is the function where you want the stack trace to start.
+
+For example, the below code will make `err.stack` point to the code calling `fn()`, even though the error was thrown at `myInner`.
+
+```ts
+const fn = () => {
+  function myInner() {
+    throw err;
+  }
+
+  try {
+    myInner();
+  } catch (err) {
+    console.log(err.stack);
+    console.log("");
+    console.log("-- captureStackTrace --");
+    console.log("");
+    Error.captureStackTrace(err, fn);
+    console.log(err.stack);
+  }
+};
+
+fn();
+```
+
+This logs the following:
+
+```sh
+Error: here!
+    at myInner (file.js:4:15)
+    at fn (file.js:8:5)
+    at module code (file.js:17:1)
+    at moduleEvaluation (native)
+    at moduleEvaluation (native)
+    at <anonymous> (native)
+
+-- captureStackTrace --
+
+Error: here!
+    at module code (file.js:17:1)
+    at moduleEvaluation (native)
+    at moduleEvaluation (native)
+    at <anonymous> (native)
+```

package/docs/runtime/env.md

@@ -0,0 +1,214 @@
+Bun reads your `.env` files automatically and provides idiomatic ways to read and write your environment variables programmatically. Plus, some aspects of Bun's runtime behavior can be configured with Bun-specific environment variables.
+
+## Setting environment variables
+
+Bun reads the following files automatically (listed in order of increasing precedence).
+
+- `.env`
+- `.env.production`, `.env.development`, `.env.test` (depending on value of `NODE_ENV`)
+- `.env.local`
+
+```txt#.env
+FOO=hello
+BAR=world
+```
+
+Variables can also be set via the command line.
+
+```sh
+$ FOO=helloworld bun run dev
+```
+
+Or programmatically by assigning a property to `process.env`.
+
+```ts
+process.env.FOO = "hello";
+```
+
+### Manually specifying `.env` files
+
+Bun supports `--env-file` to override which specific `.env` file to load. You can use `--env-file` when running scripts in bun's runtime, or when running package.json scripts.
+
+```sh
+bun --env-file=.env.1 src/index.ts
+
+bun --env-file=.env.abc --env-file=.env.def run build
+```
+
+### Quotation marks
+
+Bun supports double quotes, single quotes, and template literal backticks:
+
+```txt#.env
+FOO='hello'
+FOO="hello"
+FOO=`hello`
+```
+
+### Expansion
+
+Environment variables are automatically _expanded_. This means you can reference previously-defined variables in your environment variables.
+
+```txt#.env
+FOO=world
+BAR=hello$FOO
+```
+
+```ts
+process.env.BAR; // => "helloworld"
+```
+
+This is useful for constructing connection strings or other compound values.
+
+```txt#.env
+DB_USER=postgres
+DB_PASSWORD=secret
+DB_HOST=localhost
+DB_PORT=5432
+DB_URL=postgres://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME
+```
+
+This can be disabled by escaping the `$` with a backslash.
+
+```txt#.env
+FOO=world
+BAR=hello\$FOO
+```
+
+```ts
+process.env.BAR; // => "hello$FOO"
+```
+
+### `dotenv`
+
+Generally speaking, you won't need `dotenv` or `dotenv-expand` anymore, because Bun reads `.env` files automatically.
+
+## Reading environment variables
+
+The current environment variables can be accessed via `process.env`.
+
+```ts
+process.env.API_TOKEN; // => "secret"
+```
+
+Bun also exposes these variables via `Bun.env` and `import.meta.env`, which is a simple alias of `process.env`.
+
+```ts
+Bun.env.API_TOKEN; // => "secret"
+import.meta.env.API_TOKEN; // => "secret"
+```
+
+To print all currently-set environment variables to the command line, run `bun --print process.env`. This is useful for debugging.
+
+```sh
+$ bun --print process.env
+BAZ=stuff
+FOOBAR=aaaaaa
+<lots more lines>
+```
+
+## TypeScript
+
+In TypeScript, all properties of `process.env` are typed as `string | undefined`.
+
+```ts
+Bun.env.whatever;
+// string | undefined
+```
+
+To get autocompletion and tell TypeScript to treat a variable as a non-optional string, we'll use [interface merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#merging-interfaces).
+
+```ts
+declare module "bun" {
+  interface Env {
+    AWESOME: string;
+  }
+}
+```
+
+Add this line to any file in your project. It will globally add the `AWESOME` property to `process.env` and `Bun.env`.
+
+```ts
+process.env.AWESOME; // => string
+```
+
+## Configuring Bun
+
+These environment variables are read by Bun and configure aspects of its behavior.
+
+{% table %}
+
+- Name
+- Description
+
+---
+
+- `NODE_TLS_REJECT_UNAUTHORIZED`
+- `NODE_TLS_REJECT_UNAUTHORIZED=0` disables SSL certificate validation. This is useful for testing and debugging, but you should be very hesitant to use this in production. Note: This environment variable was originally introduced by Node.js and we kept the name for compatibility.
+
+---
+
+- `BUN_CONFIG_VERBOSE_FETCH`
+- If `BUN_CONFIG_VERBOSE_FETCH=curl`, then fetch requests will log the url, method, request headers and response headers to the console. This is useful for debugging network requests. This also works with `node:http`. `BUN_CONFIG_VERBOSE_FETCH=1` is equivalent to `BUN_CONFIG_VERBOSE_FETCH=curl` except without the `curl` output.
+
+---
+
+- `BUN_RUNTIME_TRANSPILER_CACHE_PATH`
+- The runtime transpiler caches the transpiled output of source files larger than 50 kb. This makes CLIs using Bun load faster. If `BUN_RUNTIME_TRANSPILER_CACHE_PATH` is set, then the runtime transpiler will cache transpiled output to the specified directory. If `BUN_RUNTIME_TRANSPILER_CACHE_PATH` is set to an empty string or the string `"0"`, then the runtime transpiler will not cache transpiled output. If `BUN_RUNTIME_TRANSPILER_CACHE_PATH` is unset, then the runtime transpiler will cache transpiled output to the platform-specific cache directory.
+
+---
+
+- `TMPDIR`
+- Bun occasionally requires a directory to store intermediate assets during bundling or other operations. If unset, defaults to the platform-specific temporary directory: `/tmp` on Linux, `/private/tmp` on macOS.
+
+---
+
+- `NO_COLOR`
+- If `NO_COLOR=1`, then ANSI color output is [disabled](https://no-color.org/).
+
+---
+
+- `FORCE_COLOR`
+- If `FORCE_COLOR=1`, then ANSI color output is force enabled, even if `NO_COLOR` is set.
+
+---
+
+- `BUN_CONFIG_MAX_HTTP_REQUESTS`
+- Control the maximum number of concurrent HTTP requests sent by fetch and `bun install`. Defaults to `256`. If you are running into rate limits or connection issues, you can reduce this number.
+
+---
+
+- `BUN_CONFIG_NO_CLEAR_TERMINAL_ON_RELOAD`
+- If `BUN_CONFIG_NO_CLEAR_TERMINAL_ON_RELOAD=true`, then `bun --watch` will not clear the console on reload
+
+---
+
+- `DO_NOT_TRACK`
+- Disable uploading crash reports to `bun.report` on crash. On macOS & Windows, crash report uploads are enabled by default. Otherwise, telemetry is not sent yet as of May 21st, 2024, but we are planning to add telemetry in the coming weeks. If `DO_NOT_TRACK=1`, then auto-uploading crash reports and telemetry are both [disabled](https://do-not-track.dev/).
+
+{% /table %}
+
+## Runtime transpiler caching
+
+For files larger than 50 KB, Bun caches transpiled output into `$BUN_RUNTIME_TRANSPILER_CACHE_PATH` or the platform-specific cache directory. This makes CLIs using Bun load faster.
+
+This transpiler cache is global and shared across all projects. It is safe to delete the cache at any time. It is a content-addressable cache, so it will never contain duplicate entries. It is also safe to delete the cache while a Bun process is running.
+
+It is recommended to disable this cache when using ephemeral filesystems like Docker. Bun's Docker images automatically disable this cache.
+
+### Disable the runtime transpiler cache
+
+To disable the runtime transpiler cache, set `BUN_RUNTIME_TRANSPILER_CACHE_PATH` to an empty string or the string `"0"`.
+
+```sh
+BUN_RUNTIME_TRANSPILER_CACHE_PATH=0 bun run dev
+```
+
+### What does it cache?
+
+It caches:
+
+- The transpiled output of source files larger than 50 KB.
+- The sourcemap for the transpiled output of the file
+
+The file extension `.pile` is used for these cached files.

package/docs/runtime/hot.md

@@ -0,0 +1,139 @@
+Bun supports two kinds of automatic reloading via CLI flags:
+
+- `--watch` mode, which hard restarts Bun's process when imported files change.
+- `--hot` mode, which soft reloads the code (without restarting the process) when imported files change.
+
+## `--watch` mode
+
+Watch mode can be used with `bun test` or when running TypeScript, JSX, and JavaScript files.
+
+To run a file in `--watch` mode:
+
+```bash
+$ bun --watch index.tsx
+```
+
+To run your tests in `--watch` mode:
+
+```bash
+$ bun --watch test
+```
+
+In `--watch` mode, Bun keeps track of all imported files and watches them for changes. When a change is detected, Bun restarts the process, preserving the same set of CLI arguments and environment variables used in the initial run. If Bun crashes, `--watch` will attempt to automatically restart the process.
+
+{% callout %}
+
+**⚡️ Reloads are fast.** The filesystem watchers you're probably used to have several layers of libraries wrapping the native APIs or worse, rely on polling.
+
+Instead, Bun uses operating system native filesystem watcher APIs like kqueue or inotify to detect changes to files. Bun also does a number of optimizations to enable it scale to larger projects (such as setting a high rlimit for file descriptors, statically allocated file path buffers, reuse file descriptors when possible, etc).
+
+{% /callout %}
+
+The following examples show Bun live-reloading a file as it is edited, with VSCode configured to save the file [on each keystroke](https://code.visualstudio.com/docs/editor/codebasics#_save-auto-save).
+
+{% codetabs %}
+
+```bash
+$ bun run --watch watchy.tsx
+```
+
+```tsx#watchy.tsx
+import { serve } from "bun";
+console.log("I restarted at:", Date.now());
+
+serve({
+  port: 4003,
+
+  fetch(request) {
+    return new Response("Sup");
+  },
+});
+```
+
+{% /codetabs %}
+
+In this example, Bun is
+![bun watch gif](https://user-images.githubusercontent.com/709451/228439002-7b9fad11-0db2-4e48-b82d-2b88c8625625.gif)
+
+Running `bun test` in watch mode and `save-on-keypress` enabled:
+
+```bash
+$ bun --watch test
+```
+
+![bun test gif](https://user-images.githubusercontent.com/709451/228396976-38a23864-4a1d-4c96-87cc-04e5181bf459.gif)
+
+## `--hot` mode
+
+Use `bun --hot` to enable hot reloading when executing code with Bun. This is distinct from `--watch` mode in that Bun does not hard-restart the entire process. Instead, it detects code changes and updates its internal module cache with the new code.
+
+**Note** — This is not the same as hot reloading in the browser! Many frameworks provide a "hot reloading" experience, where you can edit & save your frontend code (say, a React component) and see the changes reflected in the browser without refreshing the page. Bun's `--hot` is the server-side equivalent of this experience. To get hot reloading in the browser, use a framework like [Vite](https://vitejs.dev).
+
+```bash
+$ bun --hot server.ts
+```
+
+Starting from the entrypoint (`server.ts` in the example above), Bun builds a registry of all imported source files (excluding those in `node_modules`) and watches them for changes. When a change is detected, Bun performs a "soft reload". All files are re-evaluated, but all global state (notably, the `globalThis` object) is persisted.
+
+```ts#server.ts
+// make TypeScript happy
+declare global {
+  var count: number;
+}
+
+globalThis.count ??= 0;
+console.log(`Reloaded ${globalThis.count} times`);
+globalThis.count++;
+
+// prevent `bun run` from exiting
+setInterval(function () {}, 1000000);
+```
+
+If you run this file with `bun --hot server.ts`, you'll see the reload count increment every time you save the file.
+
+```bash
+$ bun --hot index.ts
+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` is able to reflect the updated code without restarting the process.
+
+### HTTP servers
+
+This makes it possible, for instance, to update your HTTP request handler without shutting down the server itself. When you save the file, your HTTP server will be reloaded with the updated code without the process being restarted. This results in seriously fast refresh speeds.
+
+```ts#server.ts
+globalThis.count ??= 0;
+globalThis.count++;
+
+Bun.serve({
+  fetch(req: Request) {
+    return new Response(`Reloaded ${globalThis.count} times`);
+  },
+  port: 3000,
+});
+```
+
+<!-- The file above is simply exporting an object with a `fetch` handler defined. When this file is executed, Bun interprets this as an HTTP server and passes the exported object into `Bun.serve`. -->
+
+<!-- {% image src="https://user-images.githubusercontent.com/709451/195477632-5fd8a73e-014d-4589-9ba2-e075ad9eb040.gif" alt="Bun vs Nodemon refresh speeds" caption="Bun on the left, Nodemon on the right." /%} -->
+
+{% callout %}
+**Note** — In a future version of Bun, support for Vite's `import.meta.hot` is planned to enable better lifecycle management for hot reloading and to align with the ecosystem.
+
+{% /callout %}
+
+{% details summary="Implementation details" %}
+
+On hot reload, Bun:
+
+- Resets the internal `require` cache and ES module registry (`Loader.registry`)
+- Runs the garbage collector synchronously (to minimize memory leaks, at the cost of runtime performance)
+- Re-transpiles all of your code from scratch (including sourcemaps)
+- Re-evaluates the code with JavaScriptCore
+
+This implementation isn't particularly optimized. It re-transpiles files that haven't changed. It makes no attempt at incremental compilation. It's a starting point.
+
+{% /details %}