1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
Bun supports two kinds of automatic reloading via CLI flags:
- `--watch` mode, which hard restarts Bun's process when imported files change (introduced in Bun v0.5.9)
- `--hot` mode, which soft reloads the code (without restarting the process) when imported files change (introduced in Bun v0.2.0)
## `--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 index.tsx --watch
```
To run your tests in `--watch` mode:
```bash
$ bun test --watch
```
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 watchy.tsx --watch
```
```tsx#watchy.tsx
import { serve } from "bun";
console.log("I restarted at:", Date.now());
serve({
port: 4003,
fetch(request) {
return new Response("Sup");
},
});
```
{% /codetabs %}
Running `bun test` in watch mode and `save-on-keypress` enabled:
```bash
$ bun test --watch
```
## `--hot` mode
Use `bun --hot` to enable hot reloading when executing code with Bun.
```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 = 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
Bun provides the following simplified API for implementing HTTP servers. Refer to [API > HTTP](/docs/api/http) for full details.
```ts#server.ts
import {type Serve} from "bun";
globalThis.count = globalThis.count ?? 0;
globalThis.count++;
export default {
fetch(req: Request) {
return new Response(`Reloaded ${globalThis.count} times`);
},
port: 3000,
} satisfies Serve;
```
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`.
Unlike an explicit call to `Bun.serve`, the object-based syntax works out of the box with `bun --hot`. When you save the file, your HTTP server be reloaded with the updated code without the process being restarted. This results in seriously fast refresh speeds.
{% 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." /%}
For more fine-grained control, you can use the `Bun.serve` API directly and handle the server reloading manually.
```ts#server.ts
import type {Serve, Server} from "bun";
// make TypeScript happy
declare global {
var count: number;
var server: Server;
}
globalThis.count = globalThis.count ?? 0;
globalThis.count++;
// define server parameters
const serverOptions: Serve = {
port: 3000,
fetch(req) {
return new Response(`Reloaded ${globalThis.count} times`);
}
};
if (!globalThis.server) {
globalThis.server = Bun.serve(serverOptions);
} else {
// reload server
globalThis.server.reload(serverOptions);
}
```
{% 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 %}
|
