bun-types 1.2.17-canary.20250620T140557 → 1.2.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/api/fetch.md CHANGED
@@ -337,7 +337,7 @@ This will print the request and response headers to your terminal:
337
337
  ```sh
338
338
  [fetch] > HTTP/1.1 GET http://example.com/
339
339
  [fetch] > Connection: keep-alive
340
- [fetch] > User-Agent: Bun/1.2.17-canary.20250620T140557
340
+ [fetch] > User-Agent: Bun/1.2.17
341
341
  [fetch] > Accept: */*
342
342
  [fetch] > Host: example.com
343
343
  [fetch] > Accept-Encoding: gzip, deflate, br
package/docs/api/http.md CHANGED
@@ -326,7 +326,11 @@ Bun.serve({
326
326
 
327
327
  ### HTML imports
328
328
 
329
- To add a client-side single-page app, you can use an HTML import:
329
+ Bun supports importing HTML files directly into your server code, enabling full-stack applications with both server-side and client-side code. HTML imports work in two modes:
330
+
331
+ **Development (`bun --hot`):** Assets are bundled on-demand at runtime, enabling hot module replacement (HMR) for a fast, iterative development experience. When you change your frontend code, the browser automatically updates without a full page reload.
332
+
333
+ **Production (`bun build`):** When building with `bun build --target=bun`, the `import index from "./index.html"` statement resolves to a pre-built manifest object containing all bundled client assets. `Bun.serve` consumes this manifest to serve optimized assets with zero runtime bundling overhead. This is ideal for deploying to production.
330
334
 
331
335
  ```ts
332
336
  import myReactSinglePageApp from "./index.html";
@@ -338,9 +342,9 @@ Bun.serve({
338
342
  });
339
343
  ```
340
344
 
341
- HTML imports don't just serve HTML. It's a full-featured frontend bundler, transpiler, and toolkit built using Bun's [bundler](https://bun.sh/docs/bundler), JavaScript transpiler and CSS parser.
345
+ HTML imports don't just serve HTML — it's a full-featured frontend bundler, transpiler, and toolkit built using Bun's [bundler](https://bun.sh/docs/bundler), JavaScript transpiler and CSS parser. You can use this to build full-featured frontends with React, TypeScript, Tailwind CSS, and more.
342
346
 
343
- You can use this to build a full-featured frontend with React, TypeScript, Tailwind CSS, and more. Check out [/docs/bundler/fullstack](https://bun.sh/docs/bundler/fullstack) to learn more.
347
+ For a complete guide on building full-stack applications with HTML imports, including detailed examples and best practices, see [/docs/bundler/fullstack](https://bun.sh/docs/bundler/fullstack).
344
348
 
345
349
  ### Practical example: REST API
346
350
 
package/docs/api/spawn.md CHANGED
@@ -120,7 +120,7 @@ You can read results from the subprocess via the `stdout` and `stderr` propertie
120
120
  ```ts
121
121
  const proc = Bun.spawn(["bun", "--version"]);
122
122
  const text = await new Response(proc.stdout).text();
123
- console.log(text); // => "1.2.17-canary.20250620T140557"
123
+ console.log(text); // => "1.2.17"
124
124
  ```
125
125
 
126
126
  Configure the output stream by passing one of the following values to `stdout/stderr`:
@@ -126,6 +126,81 @@ The `--sourcemap` argument embeds a sourcemap compressed with zstd, so that erro
126
126
 
127
127
  The `--bytecode` argument enables bytecode compilation. Every time you run JavaScript code in Bun, JavaScriptCore (the engine) will compile your source code into bytecode. We can move this parsing work from runtime to bundle time, saving you startup time.
128
128
 
129
+ ## Full-stack executables
130
+
131
+ {% note %}
132
+
133
+ New in Bun v1.2.17
134
+
135
+ {% /note %}
136
+
137
+ Bun's `--compile` flag can create standalone executables that contain both server and client code, making it ideal for full-stack applications. When you import an HTML file in your server code, Bun automatically bundles all frontend assets (JavaScript, CSS, etc.) and embeds them into the executable. When Bun sees the HTML import on the server, it kicks off a frontend build process to bundle JavaScript, CSS, and other assets.
138
+
139
+ {% codetabs %}
140
+
141
+ ```ts#server.ts
142
+ import { serve } from "bun";
143
+ import index from "./index.html";
144
+
145
+ const server = serve({
146
+ routes: {
147
+ "/": index,
148
+ "/api/hello": { GET: () => Response.json({ message: "Hello from API" }) },
149
+ },
150
+ });
151
+
152
+ console.log(`Server running at http://localhost:${server.port}`);
153
+ ```
154
+
155
+ ```html#index.html
156
+ <!DOCTYPE html>
157
+ <html>
158
+ <head>
159
+ <title>My App</title>
160
+ <link rel="stylesheet" href="./styles.css">
161
+ </head>
162
+ <body>
163
+ <h1>Hello World</h1>
164
+ <script src="./app.js"></script>
165
+ </body>
166
+ </html>
167
+ ```
168
+
169
+ ```js#app.js
170
+ console.log("Hello from the client!");
171
+ ```
172
+
173
+ ```css#styles.css
174
+ body {
175
+ background-color: #f0f0f0;
176
+ }
177
+ ```
178
+
179
+ {% /codetabs %}
180
+
181
+ To build this into a single executable:
182
+
183
+ ```sh
184
+ bun build --compile ./server.ts --outfile myapp
185
+ ```
186
+
187
+ This creates a self-contained binary that includes:
188
+
189
+ - Your server code
190
+ - The Bun runtime
191
+ - All frontend assets (HTML, CSS, JavaScript)
192
+ - Any npm packages used by your server
193
+
194
+ The result is a single file that can be deployed anywhere without needing Node.js, Bun, or any dependencies installed. Just run:
195
+
196
+ ```sh
197
+ ./myapp
198
+ ```
199
+
200
+ Bun automatically handles serving the frontend assets with proper MIME types and cache headers. The HTML import is replaced with a manifest object that `Bun.serve` uses to efficiently serve pre-bundled assets.
201
+
202
+ For more details on building full-stack applications with Bun, see the [full-stack guide](/docs/bundler/fullstack).
203
+
129
204
  ## Worker
130
205
 
131
206
  To use workers in a standalone executable, add the worker's entrypoint to the CLI arguments:
@@ -174,7 +249,7 @@ $ ./hello
174
249
 
175
250
  Standalone executables support embedding files.
176
251
 
177
- To embed files into an executable with `bun build --compile`, import the file in your code
252
+ To embed files into an executable with `bun build --compile`, import the file in your code.
178
253
 
179
254
  ```ts
180
255
  // this becomes an internal file path
@@ -353,5 +428,4 @@ Currently, the `--compile` flag can only accept a single entrypoint at a time an
353
428
  - `--splitting`
354
429
  - `--public-path`
355
430
  - `--target=node` or `--target=browser`
356
- - `--format` - always outputs a binary executable. Internally, it's almost esm.
357
431
  - `--no-bundle` - we always bundle everything into the executable.
@@ -1,5 +1,3 @@
1
- Using `Bun.serve()`'s `routes` option, you can run your frontend and backend in the same app with no extra steps.
2
-
3
1
  To get started, import HTML files and pass them to the `routes` option in `Bun.serve()`.
4
2
 
5
3
  ```ts
@@ -234,7 +232,92 @@ When `console: true` is set, Bun will stream console logs from the browser to th
234
232
 
235
233
  #### Production mode
236
234
 
237
- When serving your app in production, set `development: false` in `Bun.serve()`.
235
+ Hot reloading and `development: true` helps you iterate quickly, but in production, your server should be as fast as possible and have as few external dependencies as possible.
236
+
237
+ ##### Ahead of time bundling (recommended)
238
+
239
+ As of Bun v1.2.17, you can use `Bun.build` or `bun build` to bundle your full-stack application ahead of time.
240
+
241
+ ```sh
242
+ $ bun build --target=bun --production --outdir=dist ./src/index.ts
243
+ ```
244
+
245
+ When Bun's bundler sees an HTML import from server-side code, it will bundle the referenced JavaScript/TypeScript/TSX/JSX and CSS files into a manifest object that Bun.serve() can use to serve the assets.
246
+
247
+ ```ts
248
+ import { serve } from "bun";
249
+ import index from "./index.html";
250
+
251
+ serve({
252
+ routes: { "/": index },
253
+ });
254
+ ```
255
+
256
+ {% details summary="Internally, the `index` variable is a manifest object that looks something like this" %}
257
+
258
+ ```json
259
+ {
260
+ "index": "./index.html",
261
+ "files": [
262
+ {
263
+ "input": "index.html",
264
+ "path": "./index-f2me3qnf.js",
265
+ "loader": "js",
266
+ "isEntry": true,
267
+ "headers": {
268
+ "etag": "eet6gn75",
269
+ "content-type": "text/javascript;charset=utf-8"
270
+ }
271
+ },
272
+ {
273
+ "input": "index.html",
274
+ "path": "./index.html",
275
+ "loader": "html",
276
+ "isEntry": true,
277
+ "headers": {
278
+ "etag": "r9njjakd",
279
+ "content-type": "text/html;charset=utf-8"
280
+ }
281
+ },
282
+ {
283
+ "input": "index.html",
284
+ "path": "./index-gysa5fmk.css",
285
+ "loader": "css",
286
+ "isEntry": true,
287
+ "headers": {
288
+ "etag": "50zb7x61",
289
+ "content-type": "text/css;charset=utf-8"
290
+ }
291
+ },
292
+ {
293
+ "input": "logo.svg",
294
+ "path": "./logo-kygw735p.svg",
295
+ "loader": "file",
296
+ "isEntry": false,
297
+ "headers": {
298
+ "etag": "kygw735p",
299
+ "content-type": "application/octet-stream"
300
+ }
301
+ },
302
+ {
303
+ "input": "react.svg",
304
+ "path": "./react-ck11dneg.svg",
305
+ "loader": "file",
306
+ "isEntry": false,
307
+ "headers": {
308
+ "etag": "ck11dneg",
309
+ "content-type": "application/octet-stream"
310
+ }
311
+ }
312
+ ]
313
+ }
314
+ ```
315
+
316
+ {% /details %}
317
+
318
+ ##### Runtime bundling
319
+
320
+ When adding a build step is too complicated, you can set `development: false` in `Bun.serve()`.
238
321
 
239
322
  - Enable in-memory caching of bundled assets. Bun will bundle assets lazily on the first request to an `.html` file, and cache the result in memory until the server restarts.
240
323
  - Enables `Cache-Control` headers and `ETag` headers
@@ -26,6 +26,7 @@ The bundler is a key piece of infrastructure in the JavaScript ecosystem. As a b
26
26
  - **Reducing HTTP requests.** A single package in `node_modules` may consist of hundreds of files, and large applications may have dozens of such dependencies. Loading each of these files with a separate HTTP request becomes untenable very quickly, so bundlers are used to convert our application source code into a smaller number of self-contained "bundles" that can be loaded with a single request.
27
27
  - **Code transforms.** Modern apps are commonly built with languages or tools like TypeScript, JSX, and CSS modules, all of which must be converted into plain JavaScript and CSS before they can be consumed by a browser. The bundler is the natural place to configure these transformations.
28
28
  - **Framework features.** Frameworks rely on bundler plugins & code transformations to implement common patterns like file-system routing, client-server code co-location (think `getServerSideProps` or Remix loaders), and server components.
29
+ - **Full-stack Applications.** Bun's bundler can handle both server and client code in a single command, enabling optimized production builds and single-file executables. With build-time HTML imports, you can bundle your entire application — frontend assets and backend server — into a single deployable unit.
29
30
 
30
31
  Let's jump into the bundler API.
31
32
 
@@ -324,7 +325,7 @@ Depending on the target, Bun will apply different module resolution rules and op
324
325
  ---
325
326
 
326
327
  - `bun`
327
- - For generating bundles that are intended to be run by the Bun runtime. In many cases, it isn't necessary to bundle server-side code; you can directly execute the source code without modification. However, bundling your server code can reduce startup times and improve running performance.
328
+ - For generating bundles that are intended to be run by the Bun runtime. In many cases, it isn't necessary to bundle server-side code; you can directly execute the source code without modification. However, bundling your server code can reduce startup times and improve running performance. This is the target to use for building full-stack applications with build-time HTML imports, where both server and client code are bundled together.
328
329
 
329
330
  All bundles generated with `target: "bun"` are marked with a special `// @bun` pragma, which indicates to the Bun runtime that there's no need to re-transpile the file before execution.
330
331
 
@@ -262,6 +262,20 @@ Currently, the list of selectors is:
262
262
  - `video[poster]`
263
263
  - `video[src]`
264
264
 
265
+ {% callout %}
266
+
267
+ **HTML Loader Behavior in Different Contexts**
268
+
269
+ The `html` loader behaves differently depending on how it's used:
270
+
271
+ 1. **Static Build:** When you run `bun build ./index.html`, Bun produces a static site with all assets bundled and hashed.
272
+
273
+ 2. **Runtime:** When you run `bun run server.ts` (where `server.ts` imports an HTML file), Bun bundles assets on-the-fly during development, enabling features like hot module replacement.
274
+
275
+ 3. **Full-stack Build:** When you run `bun build --target=bun server.ts` (where `server.ts` imports an HTML file), the import resolves to a manifest object that `Bun.serve` uses to efficiently serve pre-bundled assets in production.
276
+
277
+ {% /callout %}
278
+
265
279
  ### `sh` loader
266
280
 
267
281
  **Bun Shell loader**. Default for `.sh` files
@@ -125,7 +125,7 @@ In Bun's CLI, simple boolean flags like `--minify` do not accept an argument. Ot
125
125
 
126
126
  - `--target`
127
127
  - n/a
128
- - No supported. Bun's bundler performs no syntactic down-leveling at this time.
128
+ - Not supported. Bun's bundler performs no syntactic down-leveling at this time.
129
129
 
130
130
  ---
131
131
 
@@ -7,7 +7,7 @@ Use `bun publish` to publish a package to the npm registry.
7
7
  $ bun publish
8
8
 
9
9
  ## Output
10
- bun publish v1.2.17-canary.20250620T140557 (ca7428e9)
10
+ bun publish v1.2.17 (ca7428e9)
11
11
 
12
12
  packed 203B package.json
13
13
  packed 224B README.md
@@ -9,7 +9,7 @@ $ bunx nuxi init my-nuxt-app
9
9
  ✔ Which package manager would you like to use?
10
10
  bun
11
11
  ◐ Installing dependencies...
12
- bun install v1.2.17-canary.20250620T140557 (16b4bf34)
12
+ bun install v1.2.17 (16b4bf34)
13
13
  + @nuxt/devtools@0.8.2
14
14
  + nuxt@3.7.0
15
15
  785 packages installed [2.67s]
@@ -15,7 +15,7 @@ This will add the package to `peerDependencies` in `package.json`.
15
15
  ```json-diff
16
16
  {
17
17
  "peerDependencies": {
18
- + "@types/bun": "^1.2.17-canary.20250620T140557"
18
+ + "@types/bun": "^1.2.17"
19
19
  }
20
20
  }
21
21
  ```
@@ -27,7 +27,7 @@ Running `bun install` will install peer dependencies by default, unless marked o
27
27
  ```json-diff
28
28
  {
29
29
  "peerDependencies": {
30
- "@types/bun": "^1.2.17-canary.20250620T140557"
30
+ "@types/bun": "^1.2.17"
31
31
  },
32
32
  "peerDependenciesMeta": {
33
33
  + "@types/bun": {
@@ -97,7 +97,7 @@ $ bun update
97
97
  $ bun update @types/bun --latest
98
98
 
99
99
  # Update a dependency to a specific version
100
- $ bun update @types/bun@1.2.17-canary.20250620T140557
100
+ $ bun update @types/bun@1.2.17
101
101
 
102
102
  # Update all dependencies to the latest versions
103
103
  $ bun update --latest
@@ -21,7 +21,7 @@ Here's what the output of a typical test run looks like. In this case, there are
21
21
 
22
22
  ```sh
23
23
  $ bun test
24
- bun test v1.2.17-canary.20250620T140557 (9c68abdb)
24
+ bun test v1.2.17 (9c68abdb)
25
25
 
26
26
  test.test.js:
27
27
  ✓ add [0.87ms]
@@ -47,7 +47,7 @@ To only run certain test files, pass a positional argument to `bun test`. The ru
47
47
 
48
48
  ```sh
49
49
  $ bun test test3
50
- bun test v1.2.17-canary.20250620T140557 (9c68abdb)
50
+ bun test v1.2.17 (9c68abdb)
51
51
 
52
52
  test3.test.js:
53
53
  ✓ add [1.40ms]
@@ -85,7 +85,7 @@ Adding `-t add` will only run tests with "add" in the name. This works with test
85
85
 
86
86
  ```sh
87
87
  $ bun test -t add
88
- bun test v1.2.17-canary.20250620T140557 (9c68abdb)
88
+ bun test v1.2.17 (9c68abdb)
89
89
 
90
90
  test.test.js:
91
91
  ✓ add [1.79ms]
@@ -18,7 +18,7 @@ The first time this test is executed, Bun will evaluate the value passed into `e
18
18
 
19
19
  ```sh
20
20
  $ bun test test/snap
21
- bun test v1.2.17-canary.20250620T140557 (9c68abdb)
21
+ bun test v1.2.17 (9c68abdb)
22
22
 
23
23
  test/snap.test.ts:
24
24
  ✓ snapshot [1.48ms]
@@ -61,7 +61,7 @@ Later, when this test file is executed again, Bun will read the snapshot file an
61
61
 
62
62
  ```sh
63
63
  $ bun test
64
- bun test v1.2.17-canary.20250620T140557 (9c68abdb)
64
+ bun test v1.2.17 (9c68abdb)
65
65
 
66
66
  test/snap.test.ts:
67
67
  ✓ snapshot [1.05ms]
@@ -78,7 +78,7 @@ To update snapshots, use the `--update-snapshots` flag.
78
78
 
79
79
  ```sh
80
80
  $ bun test --update-snapshots
81
- bun test v1.2.17-canary.20250620T140557 (9c68abdb)
81
+ bun test v1.2.17 (9c68abdb)
82
82
 
83
83
  test/snap.test.ts:
84
84
  ✓ snapshot [0.86ms]
@@ -29,7 +29,7 @@ To regenerate snapshots, use the `--update-snapshots` flag.
29
29
 
30
30
  ```sh
31
31
  $ bun test --update-snapshots
32
- bun test v1.2.17-canary.20250620T140557 (9c68abdb)
32
+ bun test v1.2.17 (9c68abdb)
33
33
 
34
34
  test/snap.test.ts:
35
35
  ✓ snapshot [0.86ms]
@@ -5,7 +5,7 @@ name: Get the current Bun version
5
5
  Get the current version of Bun in a semver format.
6
6
 
7
7
  ```ts#index.ts
8
- Bun.version; // => "1.2.17-canary.20250620T140557"
8
+ Bun.version; // => "1.2.17"
9
9
  ```
10
10
 
11
11
  ---
@@ -14,7 +14,7 @@ Kernel version 5.6 or higher is strongly recommended, but the minimum is 5.1. Us
14
14
  ```bash#macOS/Linux_(curl)
15
15
  $ curl -fsSL https://bun.sh/install | bash # for macOS, Linux, and WSL
16
16
  # to install a specific version
17
- $ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.17-canary.20250620T140557"
17
+ $ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.17"
18
18
  ```
19
19
 
20
20
  ```bash#npm
@@ -189,10 +189,10 @@ Since Bun is a single binary, you can install older versions of Bun by re-runnin
189
189
 
190
190
  ### Installing a specific version of Bun on Linux/Mac
191
191
 
192
- To install a specific version of Bun, you can pass the git tag of the version you want to install to the install script, such as `bun-v1.2.0` or `bun-v1.2.17-canary.20250620T140557`.
192
+ To install a specific version of Bun, you can pass the git tag of the version you want to install to the install script, such as `bun-v1.2.0` or `bun-v1.2.17`.
193
193
 
194
194
  ```sh
195
- $ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.17-canary.20250620T140557"
195
+ $ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.17"
196
196
  ```
197
197
 
198
198
  ### Installing a specific version of Bun on Windows
@@ -201,7 +201,7 @@ On Windows, you can install a specific version of Bun by passing the version num
201
201
 
202
202
  ```sh
203
203
  # PowerShell:
204
- $ iex "& {$(irm https://bun.sh/install.ps1)} -Version 1.2.17-canary.20250620T140557"
204
+ $ iex "& {$(irm https://bun.sh/install.ps1)} -Version 1.2.17"
205
205
  ```
206
206
 
207
207
  ## Downloading Bun binaries directly
@@ -124,11 +124,11 @@ await fetch("https://example.com", {
124
124
  This prints the `fetch` request as a single-line `curl` command to let you copy-paste into your terminal to replicate the request.
125
125
 
126
126
  ```sh
127
- [fetch] $ curl --http1.1 "https://example.com/" -X POST -H "content-type: application/json" -H "Connection: keep-alive" -H "User-Agent: Bun/1.2.17-canary.20250620T140557" -H "Accept: */*" -H "Host: example.com" -H "Accept-Encoding: gzip, deflate, br" --compressed -H "Content-Length: 13" --data-raw "{\"foo\":\"bar\"}"
127
+ [fetch] $ curl --http1.1 "https://example.com/" -X POST -H "content-type: application/json" -H "Connection: keep-alive" -H "User-Agent: Bun/1.2.17" -H "Accept: */*" -H "Host: example.com" -H "Accept-Encoding: gzip, deflate, br" --compressed -H "Content-Length: 13" --data-raw "{\"foo\":\"bar\"}"
128
128
  [fetch] > HTTP/1.1 POST https://example.com/
129
129
  [fetch] > content-type: application/json
130
130
  [fetch] > Connection: keep-alive
131
- [fetch] > User-Agent: Bun/1.2.17-canary.20250620T140557
131
+ [fetch] > User-Agent: Bun/1.2.17
132
132
  [fetch] > Accept: */*
133
133
  [fetch] > Host: example.com
134
134
  [fetch] > Accept-Encoding: gzip, deflate, br
@@ -170,7 +170,7 @@ This prints the following to the console:
170
170
  [fetch] > HTTP/1.1 POST https://example.com/
171
171
  [fetch] > content-type: application/json
172
172
  [fetch] > Connection: keep-alive
173
- [fetch] > User-Agent: Bun/1.2.17-canary.20250620T140557
173
+ [fetch] > User-Agent: Bun/1.2.17
174
174
  [fetch] > Accept: */*
175
175
  [fetch] > Host: example.com
176
176
  [fetch] > Accept-Encoding: gzip, deflate, br
package/docs/test/dom.md CHANGED
@@ -55,7 +55,7 @@ Let's run this test with `bun test`:
55
55
 
56
56
  ```bash
57
57
  $ bun test
58
- bun test v1.2.17-canary.20250620T140557
58
+ bun test v1.2.17
59
59
 
60
60
  dom.test.ts:
61
61
  ✓ dom test [0.82ms]
package/package.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "1.2.17-canary.20250620T140557",
2
+ "version": "1.2.17",
3
3
  "name": "bun-types",
4
4
  "license": "MIT",
5
5
  "types": "./index.d.ts",