From 4feede90f549ec8743243685ca25ce6c88e53e53 Mon Sep 17 00:00:00 2001 From: Jarred Sumner Date: Thu, 29 Jan 2026 08:11:50 +0100 Subject: [PATCH] Add missing docs --- docs/bundler/executables.mdx | 17 +++++++ docs/bundler/index.mdx | 44 +++++++++++++++++ docs/project/benchmarking.mdx | 65 +++++++++++++++++++++++-- docs/runtime/nodejs-compat.mdx | 2 +- docs/runtime/s3.mdx | 20 +++++++- docs/runtime/shell.mdx | 2 +- docs/runtime/utils.mdx | 88 ++++++++++++++++++++++++++++++++++ 7 files changed, 230 insertions(+), 8 deletions(-) diff --git a/docs/bundler/executables.mdx b/docs/bundler/executables.mdx index 16c623424f..f2f9cd3fb6 100644 --- a/docs/bundler/executables.mdx +++ b/docs/bundler/executables.mdx @@ -365,6 +365,23 @@ The `--bytecode` argument enables bytecode compilation. Every time you run JavaS console.log(process.execArgv); // ["--smol", "--user-agent=MyBot"] ``` +### Runtime arguments via `BUN_OPTIONS` + +The `BUN_OPTIONS` environment variable is applied to standalone executables, allowing you to pass runtime flags without recompiling: + +```bash terminal icon="terminal" +# Enable CPU profiling on a compiled executable +BUN_OPTIONS="--cpu-prof" ./myapp + +# Enable heap profiling with markdown output +BUN_OPTIONS="--heap-prof-md" ./myapp + +# Combine multiple flags +BUN_OPTIONS="--smol --cpu-prof-md" ./myapp +``` + +This is useful for debugging or profiling production executables without rebuilding them. + --- ## Automatic config loading diff --git a/docs/bundler/index.mdx b/docs/bundler/index.mdx index 88a301f550..ae8772169f 100644 --- a/docs/bundler/index.mdx +++ b/docs/bundler/index.mdx @@ -1333,6 +1333,50 @@ Generate metadata about the build in a structured format. The metafile contains +#### Markdown metafile + +Use `--metafile-md` to generate a markdown metafile, which is LLM-friendly and easy to read in the terminal: + +```bash terminal icon="terminal" +bun build ./src/index.ts --outdir ./dist --metafile-md ./dist/meta.md +``` + +Both `--metafile` and `--metafile-md` can be used together: + +```bash terminal icon="terminal" +bun build ./src/index.ts --outdir ./dist --metafile ./dist/meta.json --metafile-md ./dist/meta.md +``` + +#### `metafile` option formats + +In the JavaScript API, `metafile` accepts several forms: + +```ts title="build.ts" icon="/icons/typescript.svg" +// Boolean — include metafile in the result object +await Bun.build({ + entrypoints: ['./src/index.ts'], + outdir: './dist', + metafile: true, +}); + +// String — write JSON metafile to a specific path +await Bun.build({ + entrypoints: ['./src/index.ts'], + outdir: './dist', + metafile: "./dist/meta.json", +}); + +// Object — specify separate paths for JSON and markdown output +await Bun.build({ + entrypoints: ['./src/index.ts'], + outdir: './dist', + metafile: { + json: "./dist/meta.json", + markdown: "./dist/meta.md", + }, +}); +``` + The metafile structure contains: ```ts diff --git a/docs/project/benchmarking.mdx b/docs/project/benchmarking.mdx index d73b91ee7d..acdff3e8b5 100644 --- a/docs/project/benchmarking.mdx +++ b/docs/project/benchmarking.mdx @@ -227,6 +227,26 @@ bun --cpu-prof script.js This generates a `.cpuprofile` file you can open in Chrome DevTools (Performance tab → Load profile) or VS Code's CPU profiler. +### Markdown output + +Use `--cpu-prof-md` to generate a markdown CPU profile, which is grep-friendly and designed for LLM analysis: + +```sh terminal icon="terminal" +bun --cpu-prof-md script.js +``` + +Both `--cpu-prof` and `--cpu-prof-md` can be used together to generate both formats at once: + +```sh terminal icon="terminal" +bun --cpu-prof --cpu-prof-md script.js +``` + +You can also trigger profiling via the `BUN_OPTIONS` environment variable: + +```sh terminal icon="terminal" +BUN_OPTIONS="--cpu-prof-md" bun script.js +``` + ### Options ```sh terminal icon="terminal" @@ -234,8 +254,43 @@ bun --cpu-prof --cpu-prof-name my-profile.cpuprofile script.js bun --cpu-prof --cpu-prof-dir ./profiles script.js ``` -| Flag | Description | -| ---------------------------- | -------------------- | -| `--cpu-prof` | Enable profiling | -| `--cpu-prof-name ` | Set output filename | -| `--cpu-prof-dir ` | Set output directory | +| Flag | Description | +| ---------------------------- | -------------------------------------------------------- | +| `--cpu-prof` | Generate a `.cpuprofile` JSON file (Chrome DevTools format) | +| `--cpu-prof-md` | Generate a markdown CPU profile (grep/LLM-friendly) | +| `--cpu-prof-name ` | Set output filename | +| `--cpu-prof-dir ` | Set output directory | + +## Heap profiling + +Generate heap snapshots on exit to analyze memory usage and find memory leaks. + +```sh terminal icon="terminal" +bun --heap-prof script.js +``` + +This generates a V8 `.heapsnapshot` file that can be loaded in Chrome DevTools (Memory tab → Load). + +### Markdown output + +Use `--heap-prof-md` to generate a markdown heap profile for CLI analysis: + +```sh terminal icon="terminal" +bun --heap-prof-md script.js +``` + +If both `--heap-prof` and `--heap-prof-md` are specified, the markdown format is used. + +### Options + +```sh terminal icon="terminal" +bun --heap-prof --heap-prof-name my-snapshot.heapsnapshot script.js +bun --heap-prof --heap-prof-dir ./profiles script.js +``` + +| Flag | Description | +| ----------------------------- | --------------------------------------------------------- | +| `--heap-prof` | Generate a V8 `.heapsnapshot` file on exit | +| `--heap-prof-md` | Generate a markdown heap profile on exit | +| `--heap-prof-name ` | Set output filename | +| `--heap-prof-dir ` | Set output directory | diff --git a/docs/runtime/nodejs-compat.mdx b/docs/runtime/nodejs-compat.mdx index b17f85195f..8808eafe6d 100644 --- a/docs/runtime/nodejs-compat.mdx +++ b/docs/runtime/nodejs-compat.mdx @@ -165,7 +165,7 @@ This page is updated regularly to reflect compatibility status of the latest ver ### [`node:inspector`](https://nodejs.org/api/inspector.html) -🔴 Not implemented. +🟡 Partially implemented. `Profiler` API is supported (`Profiler.enable`, `Profiler.disable`, `Profiler.start`, `Profiler.stop`, `Profiler.setSamplingInterval`). Other inspector APIs are not yet implemented. ### [`node:repl`](https://nodejs.org/api/repl.html) diff --git a/docs/runtime/s3.mdx b/docs/runtime/s3.mdx index 229a748fab..18943b847d 100644 --- a/docs/runtime/s3.mdx +++ b/docs/runtime/s3.mdx @@ -135,6 +135,18 @@ await s3file.write(JSON.stringify({ name: "John", age: 30 }), { type: "application/json", }); +// Write with content encoding (e.g. for pre-compressed data) +await s3file.write(compressedData, { + type: "application/json", + contentEncoding: "gzip", +}); + +// Write with content disposition +await s3file.write(pdfData, { + type: "application/pdf", + contentDisposition: 'attachment; filename="report.pdf"', +}); + // Write using a writer (streaming) const writer = s3file.writer({ type: "application/json" }); writer.write("Hello"); @@ -188,7 +200,13 @@ const download = s3.presign("my-file.txt"); // GET, text/plain, expires in 24 ho const upload = s3.presign("my-file", { expiresIn: 3600, // 1 hour method: "PUT", - type: "application/json", // No extension for inferring, so we can specify the content type to be JSON + type: "application/json", // Sets response-content-type in the presigned URL +}); + +// Presign with content disposition (e.g. force download with a specific filename) +const downloadUrl = s3.presign("report.pdf", { + expiresIn: 3600, + contentDisposition: 'attachment; filename="quarterly-report.pdf"', }); // You can call .presign() if on a file reference, but avoid doing so diff --git a/docs/runtime/shell.mdx b/docs/runtime/shell.mdx index 4fffeb165a..6a4d505736 100644 --- a/docs/runtime/shell.mdx +++ b/docs/runtime/shell.mdx @@ -460,7 +460,7 @@ console.log(result); // Blob(13) { size: 13, type: "text/plain" } For cross-platform compatibility, Bun Shell implements a set of builtin commands, in addition to reading commands from the PATH environment variable. - `cd`: change the working directory -- `ls`: list files in a directory +- `ls`: list files in a directory (supports `-l` for long listing format) - `rm`: remove files and directories - `echo`: print text - `pwd`: print the working directory diff --git a/docs/runtime/utils.mdx b/docs/runtime/utils.mdx index c920427c77..9f7b3c9f04 100644 --- a/docs/runtime/utils.mdx +++ b/docs/runtime/utils.mdx @@ -880,6 +880,94 @@ npm/strip-ansi 212,992 chars long-ansi 1.36 ms/iter 1.38 ms --- +## `Bun.wrapAnsi()` + +Drop-in replacement for `wrap-ansi` npm package + +`Bun.wrapAnsi(input: string, columns: number, options?: WrapAnsiOptions): string` + +Wrap text to a specified column width while preserving ANSI escape codes, hyperlinks, and handling Unicode/emoji width correctly. This is a native, high-performance alternative to the popular [`wrap-ansi`](https://www.npmjs.com/package/wrap-ansi) npm package. + +```ts +// Basic wrapping at 20 columns +Bun.wrapAnsi("The quick brown fox jumps over the lazy dog", 20); +// => "The quick brown fox\njumps over the lazy\ndog" + +// Preserves ANSI escape codes +Bun.wrapAnsi("\u001b[31mThe quick brown fox jumps over the lazy dog\u001b[0m", 20); +// => "\u001b[31mThe quick brown fox\njumps over the lazy\ndog\u001b[0m" +``` + +### Options + +```ts +Bun.wrapAnsi("Hello World", 5, { + hard: true, // Break words that exceed column width (default: false) + wordWrap: true, // Wrap at word boundaries (default: true) + trim: true, // Trim leading/trailing whitespace per line (default: true) + ambiguousIsNarrow: true, // Treat ambiguous-width characters as narrow (default: true) +}); +``` + +| Option | Default | Description | +| --- | --- | --- | +| `hard` | `false` | If `true`, break words in the middle if they exceed the column width. | +| `wordWrap` | `true` | If `true`, wrap at word boundaries. If `false`, only break at explicit newlines. | +| `trim` | `true` | If `true`, trim leading and trailing whitespace from each line. | +| `ambiguousIsNarrow` | `true` | If `true`, treat ambiguous-width Unicode characters as 1 column wide. If `false`, treat them as 2 columns wide. | + +TypeScript definition: + +```ts expandable +namespace Bun { + export function wrapAnsi( + /** + * The string to wrap + */ + input: string, + /** + * The maximum column width + */ + columns: number, + /** + * Wrapping options + */ + options?: { + /** + * If `true`, break words in the middle if they don't fit on a line. + * If `false`, only break at word boundaries. + * + * @default false + */ + hard?: boolean; + /** + * If `true`, wrap at word boundaries when possible. + * If `false`, don't perform word wrapping (only wrap at explicit newlines). + * + * @default true + */ + wordWrap?: boolean; + /** + * If `true`, trim leading and trailing whitespace from each line. + * If `false`, preserve whitespace. + * + * @default true + */ + trim?: boolean; + /** + * When it's ambiguous and `true`, count ambiguous width characters as 1 character wide. + * If `false`, count them as 2 characters wide. + * + * @default true + */ + ambiguousIsNarrow?: boolean; + }, + ): string; +} +``` + +--- + ## `serialize` & `deserialize` in `bun:jsc` To save a JavaScript value into an ArrayBuffer & back, use `serialize` and `deserialize` from the `"bun:jsc"` module.