Skip to content

docs: fix examples that do not run or type-check as written #41734

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
robobun wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: fix examples that do not run or type-check as written #41734

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0a38071
docs: fix examples that do not run or type-check as written
robobun Sep 6, 2026
8ccfbfe
docs: use sample data larger than the chunk size in the chunking exam…
robobun Sep 6, 2026
cfe059c
docs: mark outfile as unsupported in the esbuild migration table
robobun Sep 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/bundler/esbuild.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand All @@ -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

Expand Down
11 changes: 6 additions & 5 deletions docs/bundler/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
},
})
```
</Tab>
<Tab title="CLI">
```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
```
</Tab>
</Tabs>
Expand Down Expand Up @@ -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",
},
})
```

Expand Down
18 changes: 12 additions & 6 deletions docs/guides/binary/buffer-to-readablestream.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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");
Expand All @@ -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 buf = Buffer.alloc(64 * 1024); // 64 KB
const chunkSize = 16 * 1024; // four 16 KB chunks

// 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();
},
});
```

---
Expand Down
18 changes: 12 additions & 6 deletions docs/guides/binary/typedarray-to-readablestream.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -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 arr = new Uint8Array(64 * 1024); // 64 KB
const chunkSize = 16 * 1024; // four 16 KB chunks

// 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();
},
});
```

---
Expand Down
10 changes: 8 additions & 2 deletions docs/guides/runtime/import-json5.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,17 +53,23 @@ 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,
hobbies: [
'reading',
'coding',
],
}`);
}`) as Person;

console.log(data.name); // => "John Doe"
console.log(data.hobbies); // => ["reading", "coding"]
Expand Down
12 changes: 6 additions & 6 deletions docs/guides/runtime/import-xml.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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(`
<user id="7">
<name>John Doe</name>
<hobby>reading</hobby>
<hobby>coding</hobby>
</user>
`);
`) 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"
```

---
Expand Down
10 changes: 8 additions & 2 deletions docs/guides/runtime/import-yaml.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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"]
```
Expand Down
18 changes: 10 additions & 8 deletions docs/runtime/sql.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Comment thread
robobun marked this conversation as resolved.
| `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

Expand Down
21 changes: 6 additions & 15 deletions docs/test/runtime-behavior.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,30 +187,21 @@ 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.

```bash terminal icon="terminal"
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

Expand Down