> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/oven-sh/bun/llms.txt
> Use this file to discover all available pages before exploring further.

# Watch Mode

> Automatically reload your Bun scripts and tests on file changes using --watch or --hot.

Bun supports two automatic reloading modes:

* `--watch` — hard restarts the process when imported files change.
* `--hot` — soft reloads code without restarting the process.

<Tabs>
  <Tab title="--watch">
    Restarts the entire Bun process when a file changes. All global state is reset. Suitable for scripts, CLI tools, and test suites.
  </Tab>

  <Tab title="--hot">
    Re-evaluates changed modules without restarting the process. Global state on `globalThis` is preserved. Suitable for HTTP servers and long-running processes.
  </Tab>
</Tabs>

## `--watch` mode

Run a file and restart it automatically whenever any imported file changes:

```bash theme={null}
bun --watch run index.tsx
```

Run tests and re-run them on every file change:

```bash theme={null}
bun --watch test
```

In `--watch` mode, Bun:

* Tracks all imported files and watches them for changes.
* Restarts the process with the same CLI arguments and environment variables on change.
* Automatically restarts if the process crashes.

<Note>
  Bun uses operating system native filesystem APIs (`kqueue` on macOS, `inotify` on Linux) rather than polling. This makes watch mode fast even in large projects.
</Note>

### Example: live-reloading an HTTP server

```typescript theme={null}
import { serve } from "bun";

console.log("I restarted at:", Date.now());

serve({
  port: 4003,
  fetch(request) {
    return new Response("Sup");
  },
});
```

```bash theme={null}
bun --watch run server.ts
```

Every time you save `server.ts`, the process restarts and re-runs from the top.

### `--no-clear-screen`

In environments where multiple watch processes run simultaneously (e.g., with `concurrently`), use `--no-clear-screen` to prevent each reload from clearing the terminal:

```bash theme={null}
bun build --watch --no-clear-screen
```

This behaves like TypeScript's `--preserveWatchOutput`.

## `--hot` mode

Use `--hot` to enable hot reloading. Unlike `--watch`, Bun does not restart the process. Instead, it detects file changes, resets the internal module cache, and re-evaluates changed files. All global state stored on `globalThis` is preserved across reloads.

```bash theme={null}
bun --hot run server.ts
```

Starting from the entry point, Bun builds a registry of all imported source files (excluding `node_modules`) and watches them for changes.

### Tracking reload count

Because `globalThis` persists across reloads, you can use it to track state:

```typescript theme={null}
declare global {
  var count: number;
}

globalThis.count ??= 0;
console.log(`Reloaded ${globalThis.count} times`);
globalThis.count++;

// Keep the process alive
setInterval(function () {}, 1000000);
```

Running this with `bun --hot run server.ts` and saving the file prints an incrementing count:

```
Reloaded 1 times
Reloaded 2 times
Reloaded 3 times
```

### HTTP servers with `--hot`

`--hot` is particularly useful with HTTP servers. When you save the file, Bun re-evaluates the module and the server picks up the new request handler — without closing the port or losing connections.

```typescript theme={null}
globalThis.count ??= 0;
globalThis.count++;

Bun.serve({
  fetch(req: Request) {
    return new Response(`Reloaded ${globalThis.count} times`);
  },
  port: 3000,
});
```

Unlike traditional tools like `nodemon`, which restart the entire process and tear down the HTTP server, `bun --hot` reflects code changes in-place. This results in much faster iteration cycles.

<Note>
  `--hot` is the server-side equivalent of browser hot reloading. For hot reloading in the browser (e.g., React component updates without a page refresh), use a framework like [Vite](https://vite.dev).
</Note>

## Comparison

| Feature                 | `--watch`        | `--hot`            |
| ----------------------- | ---------------- | ------------------ |
| Full process restart    | Yes              | No                 |
| Global state preserved  | No               | Yes (`globalThis`) |
| Works with `bun test`   | Yes              | No                 |
| Works with HTTP servers | Yes (reconnects) | Yes (no downtime)  |
| Crash recovery          | Yes              | No                 |

## `bun test --watch`

Run your test suite in watch mode. On every file change, Bun re-runs the affected tests:

```bash theme={null}
bun --watch test
```

To run a specific test file in watch mode:

```bash theme={null}
bun --watch test src/utils.test.ts
```