From 0a380714191c6491ec35c2f49e4be9517b76b107 Mon Sep 17 00:00:00 2001 From: robobun <117481402+robobun@users.noreply.github.com> Date: Sun, 6 Sep 2026 18:42:00 +0000 Subject: [PATCH 1/3] docs: fix examples that do not run or type-check as written - bundler/index.mdx: move `outfile` under `compile` in the ESM bytecode example. A top-level `outfile` is not a BuildConfig key and is ignored. - bundler/index.mdx: use `text` and `file` in the loader map example. The `dataurl` and `base64` loaders are accepted but emit an empty string today, and are not in the `Loader` type. - test/runtime-behavior.mdx: remove `bun test --hot` and `bun test --frozen-lockfile`. The test runner only re-runs under `--watch`, and `--frozen-lockfile` is an install flag. List the auto-install flags the runtime does read. - runtime/sql.mdx: the Postgres user variable is `PGUSER` (also `PG_USER`, then `USER`). `PGUSERNAME` and `USERNAME` are never read. Document the `PG_*` aliases for the other rows. - guides/binary: `blob.stream(1024)` does not set a 1024-byte chunk size and does not type-check. Show manual chunking instead. - guides/runtime/import-{json5,yaml,xml}.mdx: `parse()` returns `unknown` (or `XML.Document`), so the property accesses on the next lines did not type-check. Cast the result to the expected shape. --- docs/bundler/index.mdx | 11 +++++----- .../binary/buffer-to-readablestream.mdx | 16 +++++++++----- .../binary/typedarray-to-readablestream.mdx | 16 +++++++++----- docs/guides/runtime/import-json5.mdx | 10 +++++++-- docs/guides/runtime/import-xml.mdx | 12 +++++------ docs/guides/runtime/import-yaml.mdx | 10 +++++++-- docs/runtime/sql.mdx | 18 +++++++++------- docs/test/runtime-behavior.mdx | 21 ++++++------------- 8 files changed, 66 insertions(+), 48 deletions(-) diff --git a/docs/bundler/index.mdx b/docs/bundler/index.mdx index c8a89aed92f6..aa45074158fa 100644 --- a/docs/bundler/index.mdx +++ b/docs/bundler/index.mdx @@ -1206,15 +1206,15 @@ A map of file extensions to built-in loader names. Use this to customize how cer entrypoints: ['./index.tsx'], outdir: './out', loader: { - ".png": "dataurl", - ".txt": "file", + ".svg": "text", + ".bin": "file", }, }) ``` ```bash terminal icon="terminal" - bun build ./index.tsx --outdir ./out --loader .png:dataurl --loader .txt:file + bun build ./index.tsx --outdir ./out --loader .svg:text --loader .bin:file ``` @@ -1677,10 +1677,11 @@ The `bytecodeDepth: number` option (a non-negative integer) limits how many leve // ESM bytecode (requires compile) await Bun.build({ entrypoints: ["./index.tsx"], - outfile: "./mycli", bytecode: true, format: "esm", - compile: true, + compile: { + outfile: "./mycli", + }, }) ``` diff --git a/docs/guides/binary/buffer-to-readablestream.mdx b/docs/guides/binary/buffer-to-readablestream.mdx index 418befa51df3..1e5a8d63e992 100644 --- a/docs/guides/binary/buffer-to-readablestream.mdx +++ b/docs/guides/binary/buffer-to-readablestream.mdx @@ -18,7 +18,7 @@ const stream = new ReadableStream({ --- -To stream the data in smaller chunks, first create a `Blob` instance from the `Buffer`, then use [`Blob.stream()`](https://developer.mozilla.org/en-US/docs/Web/API/Blob/stream) to create a `ReadableStream`. +To stream the data in smaller chunks, first create a `Blob` instance from the `Buffer`, then use [`Blob.stream()`](https://developer.mozilla.org/en-US/docs/Web/API/Blob/stream) to create a `ReadableStream`. Bun picks the chunk size. ```ts const buf = Buffer.from("hello world"); @@ -28,14 +28,20 @@ const stream = blob.stream(); --- -Pass a number to `.stream()` to set the chunk size. +To control the chunk size yourself, enqueue slices of the `Buffer`. ```ts const buf = Buffer.from("hello world"); -const blob = new Blob([buf]); +const chunkSize = 1024; -// set chunk size of 1024 bytes -const stream = blob.stream(1024); +const stream = new ReadableStream({ + start(controller) { + for (let i = 0; i < buf.length; i += chunkSize) { + controller.enqueue(buf.subarray(i, i + chunkSize)); + } + controller.close(); + }, +}); ``` --- diff --git a/docs/guides/binary/typedarray-to-readablestream.mdx b/docs/guides/binary/typedarray-to-readablestream.mdx index 2cc558aea356..dff2a339d293 100644 --- a/docs/guides/binary/typedarray-to-readablestream.mdx +++ b/docs/guides/binary/typedarray-to-readablestream.mdx @@ -18,7 +18,7 @@ const stream = new ReadableStream({ --- -To stream the data in smaller chunks, first create a `Blob` instance from the `Uint8Array`, then use [`Blob.stream()`](https://developer.mozilla.org/en-US/docs/Web/API/Blob/stream) to create a `ReadableStream`. +To stream the data in smaller chunks, first create a `Blob` instance from the `Uint8Array`, then use [`Blob.stream()`](https://developer.mozilla.org/en-US/docs/Web/API/Blob/stream) to create a `ReadableStream`. Bun picks the chunk size. ```ts const arr = new Uint8Array(64); @@ -28,14 +28,20 @@ const stream = blob.stream(); --- -Pass a number to `.stream()` to set the chunk size. +To control the chunk size yourself, enqueue slices of the `Uint8Array`. ```ts const arr = new Uint8Array(64); -const blob = new Blob([arr]); +const chunkSize = 1024; -// set chunk size of 1024 bytes -const stream = blob.stream(1024); +const stream = new ReadableStream({ + start(controller) { + for (let i = 0; i < arr.length; i += chunkSize) { + controller.enqueue(arr.subarray(i, i + chunkSize)); + } + controller.close(); + }, +}); ``` --- diff --git a/docs/guides/runtime/import-json5.mdx b/docs/guides/runtime/import-json5.mdx index 1989706ecd87..72911c485f2d 100644 --- a/docs/guides/runtime/import-json5.mdx +++ b/docs/guides/runtime/import-json5.mdx @@ -53,9 +53,15 @@ console.log(features.rateLimit); // => true --- -For parsing JSON5 strings at runtime, use `Bun.JSON5.parse()`: +For parsing JSON5 strings at runtime, use `Bun.JSON5.parse()`. It returns `unknown`, so give the result a type: ```ts config.ts icon="/icons/typescript.svg" +interface Person { + name: string; + age: number; + hobbies: string[]; +} + const data = Bun.JSON5.parse(`{ name: 'John Doe', age: 30, @@ -63,7 +69,7 @@ const data = Bun.JSON5.parse(`{ 'reading', 'coding', ], -}`); +}`) as Person; console.log(data.name); // => "John Doe" console.log(data.hobbies); // => ["reading", "coding"] diff --git a/docs/guides/runtime/import-xml.mdx b/docs/guides/runtime/import-xml.mdx index 8e8e78c525ce..9b4b4d62227e 100644 --- a/docs/guides/runtime/import-xml.mdx +++ b/docs/guides/runtime/import-xml.mdx @@ -42,20 +42,20 @@ console.log(Number(config.server["@timeout"])); // => 30 --- -For parsing XML strings at runtime, use `Bun.XML.parse()`: +For parsing XML strings at runtime, use `Bun.XML.parse()`. The result is typed as a generic document, so give it the shape you expect: ```ts config.ts icon="/icons/typescript.svg" -const data = Bun.XML.parse(` +const { user } = Bun.XML.parse(` John Doe reading coding -`); +`) as { user: { "@id": string; name: string; hobby: string[] } }; -console.log(data.user.name); // => "John Doe" -console.log(data.user.hobby); // => ["reading", "coding"] -console.log(data.user["@id"]); // => "7" +console.log(user.name); // => "John Doe" +console.log(user.hobby); // => ["reading", "coding"] +console.log(user["@id"]); // => "7" ``` --- diff --git a/docs/guides/runtime/import-yaml.mdx b/docs/guides/runtime/import-yaml.mdx index ec66128dcd66..728995d93e4b 100644 --- a/docs/guides/runtime/import-yaml.mdx +++ b/docs/guides/runtime/import-yaml.mdx @@ -57,9 +57,15 @@ config.database.port; // => 5432 --- -For parsing YAML strings at runtime, use `Bun.YAML.parse()`: +For parsing YAML strings at runtime, use `Bun.YAML.parse()`. It returns `unknown`, so give the result a type: ```ts config.ts icon="/icons/typescript.svg" +interface Person { + name: string; + age: number; + hobbies: string[]; +} + const yamlString = ` name: John Doe age: 30 @@ -68,7 +74,7 @@ hobbies: - coding `; -const data = Bun.YAML.parse(yamlString); +const data = Bun.YAML.parse(yamlString) as Person; console.log(data.name); // => "John Doe" console.log(data.hobbies); // => ["reading", "coding"] ``` diff --git a/docs/runtime/sql.mdx b/docs/runtime/sql.mdx index e14b2b9b54b0..ed8ce398a49a 100644 --- a/docs/runtime/sql.mdx +++ b/docs/runtime/sql.mdx @@ -579,14 +579,16 @@ These environment variables define the PostgreSQL connection: Without a connection URL, Bun checks these individual parameters: -| Environment Variable | Fallback Variables | Default Value | Description | -| -------------------- | ---------------------------- | ------------- | ------------------------------------------------------------------------------ | -| `PGHOST` | - | `localhost` | Database host | -| `PGPORT` | - | `5432` | Database port | -| `PGUSERNAME` | `PGUSER`, `USER`, `USERNAME` | `postgres` | Database user | -| `PGPASSWORD` | - | (empty) | Database password | -| `PGDATABASE` | - | username | Database name | -| `PGSSLMODE` | - | `disable` | SSL mode (`disable`, `allow`, `prefer`, `require`, `verify-ca`, `verify-full`) | +| Environment Variable | Also Accepted | Default Value | Description | +| -------------------- | ----------------- | ------------- | ------------------------------------------------------------------------------ | +| `PGHOST` | `PG_HOST` | `localhost` | Database host | +| `PGPORT` | `PG_PORT` | `5432` | Database port | +| `PGUSER` | `PG_USER`, `USER` | `postgres` | Database user | +| `PGPASSWORD` | `PG_PASSWORD` | (empty) | Database password | +| `PGDATABASE` | `PG_DATABASE` | username | Database name | +| `PGSSLMODE` | `PG_SSLMODE` | `disable` | SSL mode (`disable`, `allow`, `prefer`, `require`, `verify-ca`, `verify-full`) | + +When both forms are set, the `PG_*` form wins. `USER` is read only when neither `PG_USER` nor `PGUSER` is set. ### SQLite Environment Variables diff --git a/docs/test/runtime-behavior.mdx b/docs/test/runtime-behavior.mdx index 83eefb7d44b2..7c16fc600de3 100644 --- a/docs/test/runtime-behavior.mdx +++ b/docs/test/runtime-behavior.mdx @@ -187,14 +187,13 @@ bun test --env-file .env.test ### Installation-related Flags ```bash -# Affect any network requests or auto-installs during test execution -bun test --prefer-offline -bun test --frozen-lockfile +# Affect auto-installs during test execution +bun test --prefer-offline # resolve auto-installed packages from the local cache, skip staleness checks +bun test --install=fallback # auto-install only packages missing from node_modules +bun test --no-install # disable auto-install ``` -## Watch and Hot Reloading - -### Watch Mode +## Watch Mode With the `--watch` flag, the test runner watches for file changes and re-runs tests. @@ -202,15 +201,7 @@ With the `--watch` flag, the test runner watches for file changes and re-runs te bun test --watch ``` -### Hot Reloading - -The `--hot` flag is similar, but more aggressive about preserving state between runs: - -```bash terminal icon="terminal" -bun test --hot -``` - -For most tests, use `--watch`: it gives better isolation between runs. +The test runner does not support `--hot`. Each re-run starts a fresh process. ## Global Variables From 8ccfbfe91168cb2f3339ee9b6b2b2a58538ea7fc Mon Sep 17 00:00:00 2001 From: robobun <117481402+robobun@users.noreply.github.com> Date: Sun, 6 Sep 2026 18:53:38 +0000 Subject: [PATCH 2/3] docs: use sample data larger than the chunk size in the chunking examples --- docs/guides/binary/buffer-to-readablestream.mdx | 4 ++-- docs/guides/binary/typedarray-to-readablestream.mdx | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guides/binary/buffer-to-readablestream.mdx b/docs/guides/binary/buffer-to-readablestream.mdx index 1e5a8d63e992..e657d8b1c364 100644 --- a/docs/guides/binary/buffer-to-readablestream.mdx +++ b/docs/guides/binary/buffer-to-readablestream.mdx @@ -31,8 +31,8 @@ const stream = blob.stream(); To control the chunk size yourself, enqueue slices of the `Buffer`. ```ts -const buf = Buffer.from("hello world"); -const chunkSize = 1024; +const buf = Buffer.alloc(64 * 1024); // 64 KB +const chunkSize = 16 * 1024; // four 16 KB chunks const stream = new ReadableStream({ start(controller) { diff --git a/docs/guides/binary/typedarray-to-readablestream.mdx b/docs/guides/binary/typedarray-to-readablestream.mdx index dff2a339d293..7de0dd25e752 100644 --- a/docs/guides/binary/typedarray-to-readablestream.mdx +++ b/docs/guides/binary/typedarray-to-readablestream.mdx @@ -31,8 +31,8 @@ const stream = blob.stream(); To control the chunk size yourself, enqueue slices of the `Uint8Array`. ```ts -const arr = new Uint8Array(64); -const chunkSize = 1024; +const arr = new Uint8Array(64 * 1024); // 64 KB +const chunkSize = 16 * 1024; // four 16 KB chunks const stream = new ReadableStream({ start(controller) { From cfe059c818cd17cddeb05dae0289d5478816c04b Mon Sep 17 00:00:00 2001 From: robobun <117481402+robobun@users.noreply.github.com> Date: Wed, 9 Sep 2026 14:41:58 +0000 Subject: [PATCH 3/3] docs: mark outfile as unsupported in the esbuild migration table Bun.build reads outfile only inside the compile options object (CompileOptions::from_js in src/runtime/api/JSBundler.rs). A top-level outfile is ignored. Update the outfile and write rows to say so. --- docs/bundler/esbuild.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/bundler/esbuild.mdx b/docs/bundler/esbuild.mdx index 716ae790bd34..1dd619a462e8 100644 --- a/docs/bundler/esbuild.mdx +++ b/docs/bundler/esbuild.mdx @@ -152,7 +152,7 @@ In Bun's CLI, boolean flags like `--minify` take no argument. Flags that take on | `outExtension` | n/a | Not supported | | `outbase` | `root` | Different name | | `outdir` | `outdir` | No differences | -| `outfile` | `outfile` | No differences | +| `outfile` | n/a | Not supported. Use `outdir` plus `naming` to control the output file name, or `compile.outfile` for standalone executables. | | `packages` | `packages` | No differences | | `platform` | `target` | Supports `"bun"`, `"node"` and `"browser"` (the default). Does not support `"neutral"`. | | `plugins` | `plugins` | Bun's plugin API is a subset of esbuild's. Some esbuild plugins work with Bun without modification. | @@ -170,7 +170,7 @@ In Bun's CLI, boolean flags like `--minify` take no argument. Flags that take on | `target` | n/a | No support for syntax downleveling | | `treeShaking` | `treeShaking` | Defaults to `true` | | `tsconfig` | `tsconfig` | | -| `write` | n/a | Set to true if `outdir`/`outfile` is set, otherwise false | +| `write` | n/a | Set to true if `outdir` is set, otherwise false. Standalone executables (`compile`) are always written to disk. | ## Plugin API