bun-types 1.3.4 → 1.3.5-canary.20251218T140753

package/docs/bundler/executables.mdx

@@ -5,18 +5,28 @@ description: "Generate standalone executables from TypeScript or JavaScript file
 
 Bun's bundler implements a `--compile` flag for generating a standalone binary from a TypeScript or JavaScript file.
 
-<CodeGroup>
-
-```bash terminal icon="terminal"
-bun build ./cli.ts --compile --outfile mycli
-```
+<Tabs>
+  <Tab title="CLI">
+    ```bash terminal icon="terminal"
+    bun build ./cli.ts --compile --outfile mycli
+    ```
+  </Tab>
+  <Tab title="JavaScript">
+    ```ts build.ts icon="/icons/typescript.svg"
+    await Bun.build({
+      entrypoints: ["./cli.ts"],
+      compile: {
+        outfile: "./mycli",
+      },
+    });
+    ```
+  </Tab>
+</Tabs>
 
 ```ts cli.ts icon="/icons/typescript.svg"
 console.log("Hello world!");
 ```
 
-</CodeGroup>
-
 This bundles `cli.ts` into an executable that can be executed directly:
 
 ```bash terminal icon="terminal"
@@ -37,49 +47,157 @@ The `--target` flag lets you compile your standalone executable for a different
 
 To build for Linux x64 (most servers):
 
-```bash icon="terminal" terminal
-bun build --compile --target=bun-linux-x64 ./index.ts --outfile myapp
-
-# To support CPUs from before 2013, use the baseline version (nehalem)
-bun build --compile --target=bun-linux-x64-baseline ./index.ts --outfile myapp
-
-# To explicitly only support CPUs from 2013 and later, use the modern version (haswell)
-# modern is faster, but baseline is more compatible.
-bun build --compile --target=bun-linux-x64-modern ./index.ts --outfile myapp
-```
+<Tabs>
+  <Tab title="CLI">
+    ```bash icon="terminal" terminal
+    bun build --compile --target=bun-linux-x64 ./index.ts --outfile myapp
+
+    # To support CPUs from before 2013, use the baseline version (nehalem)
+    bun build --compile --target=bun-linux-x64-baseline ./index.ts --outfile myapp
+
+    # To explicitly only support CPUs from 2013 and later, use the modern version (haswell)
+    # modern is faster, but baseline is more compatible.
+    bun build --compile --target=bun-linux-x64-modern ./index.ts --outfile myapp
+    ```
+
+  </Tab>
+  <Tab title="JavaScript">
+    ```ts build.ts icon="/icons/typescript.svg"
+    // Standard Linux x64
+    await Bun.build({
+      entrypoints: ["./index.ts"],
+      compile: {
+        target: "bun-linux-x64",
+        outfile: "./myapp",
+      },
+    });
+
+    // Baseline (pre-2013 CPUs)
+    await Bun.build({
+      entrypoints: ["./index.ts"],
+      compile: {
+        target: "bun-linux-x64-baseline",
+        outfile: "./myapp",
+      },
+    });
+
+    // Modern (2013+ CPUs, faster)
+    await Bun.build({
+      entrypoints: ["./index.ts"],
+      compile: {
+        target: "bun-linux-x64-modern",
+        outfile: "./myapp",
+      },
+    });
+    ```
+
+  </Tab>
+</Tabs>
 
 To build for Linux ARM64 (e.g. Graviton or Raspberry Pi):
 
-```bash icon="terminal" terminal
-# Note: the default architecture is x64 if no architecture is specified.
-bun build --compile --target=bun-linux-arm64 ./index.ts --outfile myapp
-```
+<Tabs>
+  <Tab title="CLI">
+    ```bash icon="terminal" terminal
+    # Note: the default architecture is x64 if no architecture is specified.
+    bun build --compile --target=bun-linux-arm64 ./index.ts --outfile myapp
+    ```
+  </Tab>
+  <Tab title="JavaScript">
+    ```ts build.ts icon="/icons/typescript.svg"
+    await Bun.build({
+      entrypoints: ["./index.ts"],
+      compile: {
+        target: "bun-linux-arm64",
+        outfile: "./myapp",
+      },
+    });
+    ```
+  </Tab>
+</Tabs>
 
 To build for Windows x64:
 
-```bash icon="terminal" terminal
-bun build --compile --target=bun-windows-x64 ./path/to/my/app.ts --outfile myapp
-
-# To support CPUs from before 2013, use the baseline version (nehalem)
-bun build --compile --target=bun-windows-x64-baseline ./path/to/my/app.ts --outfile myapp
-
-# To explicitly only support CPUs from 2013 and later, use the modern version (haswell)
-bun build --compile --target=bun-windows-x64-modern ./path/to/my/app.ts --outfile myapp
-
-# note: if no .exe extension is provided, Bun will automatically add it for Windows executables
-```
+<Tabs>
+  <Tab title="CLI">
+    ```bash icon="terminal" terminal
+    bun build --compile --target=bun-windows-x64 ./path/to/my/app.ts --outfile myapp
+
+    # To support CPUs from before 2013, use the baseline version (nehalem)
+    bun build --compile --target=bun-windows-x64-baseline ./path/to/my/app.ts --outfile myapp
+
+    # To explicitly only support CPUs from 2013 and later, use the modern version (haswell)
+    bun build --compile --target=bun-windows-x64-modern ./path/to/my/app.ts --outfile myapp
+
+    # note: if no .exe extension is provided, Bun will automatically add it for Windows executables
+    ```
+
+  </Tab>
+  <Tab title="JavaScript">
+    ```ts build.ts icon="/icons/typescript.svg"
+    // Standard Windows x64
+    await Bun.build({
+      entrypoints: ["./path/to/my/app.ts"],
+      compile: {
+        target: "bun-windows-x64",
+        outfile: "./myapp", // .exe added automatically
+      },
+    });
+
+    // Baseline or modern variants
+    await Bun.build({
+      entrypoints: ["./path/to/my/app.ts"],
+      compile: {
+        target: "bun-windows-x64-baseline",
+        outfile: "./myapp",
+      },
+    });
+    ```
+
+  </Tab>
+</Tabs>
 
 To build for macOS arm64:
 
-```bash icon="terminal" terminal
-bun build --compile --target=bun-darwin-arm64 ./path/to/my/app.ts --outfile myapp
-```
+<Tabs>
+  <Tab title="CLI">
+    ```bash icon="terminal" terminal
+    bun build --compile --target=bun-darwin-arm64 ./path/to/my/app.ts --outfile myapp
+    ```
+  </Tab>
+  <Tab title="JavaScript">
+    ```ts build.ts icon="/icons/typescript.svg"
+    await Bun.build({
+      entrypoints: ["./path/to/my/app.ts"],
+      compile: {
+        target: "bun-darwin-arm64",
+        outfile: "./myapp",
+      },
+    });
+    ```
+  </Tab>
+</Tabs>
 
 To build for macOS x64:
 
-```bash icon="terminal" terminal
-bun build --compile --target=bun-darwin-x64 ./path/to/my/app.ts --outfile myapp
-```
+<Tabs>
+  <Tab title="CLI">
+    ```bash icon="terminal" terminal
+    bun build --compile --target=bun-darwin-x64 ./path/to/my/app.ts --outfile myapp
+    ```
+  </Tab>
+  <Tab title="JavaScript">
+    ```ts build.ts icon="/icons/typescript.svg"
+    await Bun.build({
+      entrypoints: ["./path/to/my/app.ts"],
+      compile: {
+        target: "bun-darwin-x64",
+        outfile: "./myapp",
+      },
+    });
+    ```
+  </Tab>
+</Tabs>
 
 ### Supported targets
 
@@ -110,9 +228,27 @@ The order of the `--target` flag does not matter, as long as they're delimited b
 
 Use the `--define` flag to inject build-time constants into your executable, such as version numbers, build timestamps, or configuration values:
 
-```bash icon="terminal" terminal
-bun build --compile --define BUILD_VERSION='"1.2.3"' --define BUILD_TIME='"2024-01-15T10:30:00Z"' src/cli.ts --outfile mycli
-```
+<Tabs>
+  <Tab title="CLI">
+    ```bash icon="terminal" terminal
+    bun build --compile --define BUILD_VERSION='"1.2.3"' --define BUILD_TIME='"2024-01-15T10:30:00Z"' src/cli.ts --outfile mycli
+    ```
+  </Tab>
+  <Tab title="JavaScript">
+    ```ts build.ts icon="/icons/typescript.svg"
+    await Bun.build({
+      entrypoints: ["./src/cli.ts"],
+      compile: {
+        outfile: "./mycli",
+      },
+      define: {
+        BUILD_VERSION: JSON.stringify("1.2.3"),
+        BUILD_TIME: JSON.stringify("2024-01-15T10:30:00Z"),
+      },
+    });
+    ```
+  </Tab>
+</Tabs>
 
 These constants are embedded directly into your compiled binary at build time, providing zero runtime overhead and enabling dead code elimination optimizations.
 
@@ -133,17 +269,50 @@ With compiled executables, you can move that cost from runtime to build-time.
 
 When deploying to production, we recommend the following:
 
-```bash icon="terminal" terminal
-bun build --compile --minify --sourcemap ./path/to/my/app.ts --outfile myapp
-```
+<Tabs>
+  <Tab title="CLI">
+    ```bash icon="terminal" terminal
+    bun build --compile --minify --sourcemap ./path/to/my/app.ts --outfile myapp
+    ```
+  </Tab>
+  <Tab title="JavaScript">
+    ```ts build.ts icon="/icons/typescript.svg"
+    await Bun.build({
+      entrypoints: ["./path/to/my/app.ts"],
+      compile: {
+        outfile: "./myapp",
+      },
+      minify: true,
+      sourcemap: "linked",
+    });
+    ```
+  </Tab>
+</Tabs>
 
 ### Bytecode compilation
 
 To improve startup time, enable bytecode compilation:
 
-```bash icon="terminal" terminal
-bun build --compile --minify --sourcemap --bytecode ./path/to/my/app.ts --outfile myapp
-```
+<Tabs>
+  <Tab title="CLI">
+    ```bash icon="terminal" terminal
+    bun build --compile --minify --sourcemap --bytecode ./path/to/my/app.ts --outfile myapp
+    ```
+  </Tab>
+  <Tab title="JavaScript">
+    ```ts build.ts icon="/icons/typescript.svg"
+    await Bun.build({
+      entrypoints: ["./path/to/my/app.ts"],
+      compile: {
+        outfile: "./myapp",
+      },
+      minify: true,
+      sourcemap: "linked",
+      bytecode: true,
+    });
+    ```
+  </Tab>
+</Tabs>
 
 Using bytecode compilation, `tsc` starts 2x faster:
 
@@ -172,9 +341,24 @@ The `--bytecode` argument enables bytecode compilation. Every time you run JavaS
 
 **`--compile-exec-argv="args"`** - Embed runtime arguments that are available via `process.execArgv`:
 
-```bash icon="terminal" terminal
-bun build --compile --compile-exec-argv="--smol --user-agent=MyBot" ./app.ts --outfile myapp
-```
+<Tabs>
+  <Tab title="CLI">
+    ```bash icon="terminal" terminal
+    bun build --compile --compile-exec-argv="--smol --user-agent=MyBot" ./app.ts --outfile myapp
+    ```
+  </Tab>
+  <Tab title="JavaScript">
+    ```ts build.ts icon="/icons/typescript.svg"
+    await Bun.build({
+      entrypoints: ["./app.ts"],
+      compile: {
+        execArgv: ["--smol", "--user-agent=MyBot"],
+        outfile: "./myapp",
+      },
+    });
+    ```
+  </Tab>
+</Tabs>
 
 ```ts app.ts icon="/icons/typescript.svg"
 // In the compiled app
@@ -183,32 +367,69 @@ console.log(process.execArgv); // ["--smol", "--user-agent=MyBot"]
 
 ---
 
-## Disabling automatic config loading
+## Automatic config loading
+
+Standalone executables can automatically load configuration files from the directory where they are run. By default:
+
+- **`tsconfig.json`** and **`package.json`** loading is **disabled** — these are typically only needed at development time, and the bundler already uses them when compiling
+- **`.env`** and **`bunfig.toml`** loading is **enabled** — these often contain runtime configuration that may vary per deployment
+
+<Note>
+  In a future version of Bun, `.env` and `bunfig.toml` may also be disabled by default for more deterministic behavior.
+</Note>
+
+### Enabling config loading at runtime
 
-By default, standalone executables look for `.env` and `bunfig.toml` files in the directory where the executable is run. You can disable this behavior at build time for deterministic execution regardless of the user's working directory.
+If your executable needs to read `tsconfig.json` or `package.json` at runtime, you can opt in with the new CLI flags:
 
 ```bash icon="terminal" terminal
-# Disable .env loading
-bun build --compile --no-compile-autoload-dotenv ./app.ts --outfile myapp
+# Enable runtime loading of tsconfig.json
+bun build --compile --compile-autoload-tsconfig ./app.ts --outfile myapp
 
-# Disable bunfig.toml loading
-bun build --compile --no-compile-autoload-bunfig ./app.ts --outfile myapp
+# Enable runtime loading of package.json
+bun build --compile --compile-autoload-package-json ./app.ts --outfile myapp
 
-# Disable both
-bun build --compile --no-compile-autoload-dotenv --no-compile-autoload-bunfig ./app.ts --outfile myapp
+# Enable both
+bun build --compile --compile-autoload-tsconfig --compile-autoload-package-json ./app.ts --outfile myapp
 ```
 
-You can also configure this via the JavaScript API:
+### Disabling config loading at runtime
 
-```ts
-await Bun.build({
-  entrypoints: ["./app.ts"],
-  compile: {
-    autoloadDotenv: false, // Disable .env loading
-    autoloadBunfig: false, // Disable bunfig.toml loading
-  },
-});
-```
+To disable `.env` or `bunfig.toml` loading for deterministic execution:
+
+<Tabs>
+  <Tab title="CLI">
+    ```bash icon="terminal" terminal
+    # Disable .env loading
+    bun build --compile --no-compile-autoload-dotenv ./app.ts --outfile myapp
+
+    # Disable bunfig.toml loading
+    bun build --compile --no-compile-autoload-bunfig ./app.ts --outfile myapp
+
+    # Disable all config loading
+    bun build --compile --no-compile-autoload-dotenv --no-compile-autoload-bunfig ./app.ts --outfile myapp
+    ```
+
+  </Tab>
+  <Tab title="JavaScript">
+    ```ts build.ts icon="/icons/typescript.svg"
+    await Bun.build({
+      entrypoints: ["./app.ts"],
+      compile: {
+        // tsconfig.json and package.json are disabled by default
+        autoloadTsconfig: true, // Enable tsconfig.json loading
+        autoloadPackageJson: true, // Enable package.json loading
+
+        // .env and bunfig.toml are enabled by default
+        autoloadDotenv: false, // Disable .env loading
+        autoloadBunfig: false, // Disable bunfig.toml loading
+        outfile: "./myapp",
+      },
+    });
+    ```
+
+  </Tab>
+</Tabs>
 
 ---
 
@@ -307,9 +528,23 @@ body {
 
 To build this into a single executable:
 
-```bash terminal icon="terminal"
-bun build --compile ./server.ts --outfile myapp
-```
+<Tabs>
+  <Tab title="CLI">
+    ```bash terminal icon="terminal"
+    bun build --compile ./server.ts --outfile myapp
+    ```
+  </Tab>
+  <Tab title="JavaScript">
+    ```ts build.ts icon="/icons/typescript.svg"
+    await Bun.build({
+      entrypoints: ["./server.ts"],
+      compile: {
+        outfile: "./myapp",
+      },
+    });
+    ```
+  </Tab>
+</Tabs>
 
 This creates a self-contained binary that includes:
 
@@ -332,11 +567,25 @@ For more details on building full-stack applications with Bun, see the [full-sta
 
 ## Worker
 
-To use workers in a standalone executable, add the worker's entrypoint to the CLI arguments:
-
-```bash terminal icon="terminal"
-bun build --compile ./index.ts ./my-worker.ts --outfile myapp
-```
+To use workers in a standalone executable, add the worker's entrypoint to the build:
+
+<Tabs>
+  <Tab title="CLI">
+    ```bash terminal icon="terminal"
+    bun build --compile ./index.ts ./my-worker.ts --outfile myapp
+    ```
+  </Tab>
+  <Tab title="JavaScript">
+    ```ts build.ts icon="/icons/typescript.svg"
+    await Bun.build({
+      entrypoints: ["./index.ts", "./my-worker.ts"],
+      compile: {
+        outfile: "./myapp",
+      },
+    });
+    ```
+  </Tab>
+</Tabs>
 
 Then, reference the worker in your code:
 
@@ -380,34 +629,141 @@ cd /home/me/Desktop
 
 ## Embed assets & files
 
-Standalone executables support embedding files.
+Standalone executables support embedding files directly into the binary. This lets you ship a single executable that contains images, JSON configs, templates, or any other assets your application needs.
+
+### How it works
+
+Use the `with { type: "file" }` [import attribute](https://github.com/tc39/proposal-import-attributes) to embed a file:
+
+```ts index.ts icon="/icons/typescript.svg"
+import icon from "./icon.png" with { type: "file" };
+
+console.log(icon);
+// During development: "./icon.png"
+// After compilation: "$bunfs/icon-a1b2c3d4.png" (internal path)
+```
+
+The import returns a **path string** that points to the embedded file. At build time, Bun:
+
+1. Reads the file contents
+2. Embeds the data into the executable
+3. Replaces the import with an internal path (prefixed with `$bunfs/`)
 
-To embed files into an executable with `bun build --compile`, import the file in your code.
+You can then read this embedded file using `Bun.file()` or Node.js `fs` APIs.
+
+### Reading embedded files with Bun.file()
+
+`Bun.file()` is the recommended way to read embedded files:
 
 ```ts index.ts icon="/icons/typescript.svg"
-// this becomes an internal file path
 import icon from "./icon.png" with { type: "file" };
 import { file } from "bun";
 
+// Get file contents as different types
+const bytes = await file(icon).arrayBuffer(); // ArrayBuffer
+const text = await file(icon).text(); // string (for text files)
+const blob = file(icon); // Blob
+
+// Stream the file in a response
 export default {
   fetch(req) {
-    // Embedded files can be streamed from Response objects
-    return new Response(file(icon));
+    return new Response(file(icon), {
+      headers: { "Content-Type": "image/png" },
+    });
   },
 };
 ```
 
-Embedded files can be read using `Bun.file`'s functions or the Node.js `fs.readFile` function (in `"node:fs"`).
+### Reading embedded files with Node.js fs
 
-For example, to read the contents of the embedded file:
+Embedded files work seamlessly with Node.js file system APIs:
 
 ```ts index.ts icon="/icons/typescript.svg"
 import icon from "./icon.png" with { type: "file" };
+import config from "./config.json" with { type: "file" };
+import { readFileSync, promises as fs } from "node:fs";
+
+// Synchronous read
+const iconBuffer = readFileSync(icon);
+
+// Async read
+const configData = await fs.readFile(config, "utf-8");
+const parsed = JSON.parse(configData);
+
+// Check file stats
+const stats = await fs.stat(icon);
+console.log(`Icon size: ${stats.size} bytes`);
+```
+
+### Practical examples
+
+#### Embedding a JSON config file
+
+```ts index.ts icon="/icons/typescript.svg"
+import configPath from "./default-config.json" with { type: "file" };
 import { file } from "bun";
 
-const bytes = await file(icon).arrayBuffer();
-// await fs.promises.readFile(icon)
-// fs.readFileSync(icon)
+// Load the embedded default configuration
+const defaultConfig = await file(configPath).json();
+
+// Merge with user config if it exists
+const userConfig = await file("./user-config.json")
+  .json()
+  .catch(() => ({}));
+const config = { ...defaultConfig, ...userConfig };
+```
+
+#### Serving static assets in an HTTP server
+
+Use `static` routes in `Bun.serve()` for efficient static file serving:
+
+```ts server.ts icon="/icons/typescript.svg"
+import favicon from "./favicon.ico" with { type: "file" };
+import logo from "./logo.png" with { type: "file" };
+import styles from "./styles.css" with { type: "file" };
+import { file, serve } from "bun";
+
+serve({
+  static: {
+    "/favicon.ico": file(favicon),
+    "/logo.png": file(logo),
+    "/styles.css": file(styles),
+  },
+  fetch(req) {
+    return new Response("Not found", { status: 404 });
+  },
+});
+```
+
+Bun automatically handles Content-Type headers and caching for static routes.
+
+#### Embedding templates
+
+```ts index.ts icon="/icons/typescript.svg"
+import templatePath from "./email-template.html" with { type: "file" };
+import { file } from "bun";
+
+async function sendWelcomeEmail(user: { name: string; email: string }) {
+  const template = await file(templatePath).text();
+  const html = template.replace("{{name}}", user.name).replace("{{email}}", user.email);
+
+  // Send email with the rendered template...
+}
+```
+
+#### Embedding binary files
+
+```ts index.ts icon="/icons/typescript.svg"
+import wasmPath from "./processor.wasm" with { type: "file" };
+import fontPath from "./font.ttf" with { type: "file" };
+import { file } from "bun";
+
+// Load a WebAssembly module
+const wasmBytes = await file(wasmPath).arrayBuffer();
+const wasmModule = await WebAssembly.instantiate(wasmBytes);
+
+// Read binary font data
+const fontData = await file(fontPath).bytes();
 ```
 
 ### Embed SQLite databases
@@ -450,11 +806,32 @@ Unfortunately, if you're using `@mapbox/node-pre-gyp` or other similar tools, yo
 
 ### Embed directories
 
-To embed a directory with `bun build --compile`, use a shell glob in your `bun build` command:
-
-```bash terminal icon="terminal"
-bun build --compile ./index.ts ./public/**/*.png
-```
+To embed a directory with `bun build --compile`, include file patterns in your build:
+
+<Tabs>
+  <Tab title="CLI">
+    ```bash terminal icon="terminal"
+    bun build --compile ./index.ts ./public/**/*.png
+    ```
+  </Tab>
+  <Tab title="JavaScript">
+    ```ts build.ts icon="/icons/typescript.svg"
+    import { Glob } from "bun";
+
+    // Expand glob pattern to file list
+    const glob = new Glob("./public/**/*.png");
+    const pngFiles = Array.from(glob.scanSync("."));
+
+    await Bun.build({
+      entrypoints: ["./index.ts", ...pngFiles],
+      compile: {
+        outfile: "./myapp",
+      },
+    });
+    ```
+
+  </Tab>
+</Tabs>
 
 Then, you can reference the files in your code:
 
@@ -474,47 +851,174 @@ This is honestly a workaround, and we expect to improve this in the future with
 
 ### Listing embedded files
 
-To get a list of all embedded files, use `Bun.embeddedFiles`:
+`Bun.embeddedFiles` gives you access to all embedded files as `Blob` objects:
 
 ```ts index.ts icon="/icons/typescript.svg"
 import "./icon.png" with { type: "file" };
+import "./data.json" with { type: "file" };
+import "./template.html" with { type: "file" };
 import { embeddedFiles } from "bun";
 
-console.log(embeddedFiles[0].name); // `icon-${hash}.png`
+// List all embedded files
+for (const blob of embeddedFiles) {
+  console.log(`${blob.name} - ${blob.size} bytes`);
+}
+// Output:
+//   icon-a1b2c3d4.png - 4096 bytes
+//   data-e5f6g7h8.json - 256 bytes
+//   template-i9j0k1l2.html - 1024 bytes
 ```
 
-`Bun.embeddedFiles` returns an array of `Blob` objects which you can use to get the size, contents, and other properties of the files.
+Each item in `Bun.embeddedFiles` is a `Blob` with a `name` property:
 
 ```ts
-embeddedFiles: Blob[]
+embeddedFiles: ReadonlyArray<Blob>;
 ```
 
-The list of embedded files excludes bundled source code like `.ts` and `.js` files.
+This is useful for dynamically serving all embedded assets using `static` routes:
+
+```ts server.ts icon="/icons/typescript.svg"
+import "./public/favicon.ico" with { type: "file" };
+import "./public/logo.png" with { type: "file" };
+import "./public/styles.css" with { type: "file" };
+import { embeddedFiles, serve } from "bun";
+
+// Build static routes from all embedded files
+const staticRoutes: Record<string, Blob> = {};
+for (const blob of embeddedFiles) {
+  // Remove hash from filename: "icon-a1b2c3d4.png" -> "icon.png"
+  const name = blob.name.replace(/-[a-f0-9]+\./, ".");
+  staticRoutes[`/${name}`] = blob;
+}
+
+serve({
+  static: staticRoutes,
+  fetch(req) {
+    return new Response("Not found", { status: 404 });
+  },
+});
+```
+
+<Note>
+  `Bun.embeddedFiles` excludes bundled source code (`.ts`, `.js`, etc.) to help protect your application's source.
+</Note>
 
 #### Content hash
 
 By default, embedded files have a content hash appended to their name. This is useful for situations where you want to serve the file from a URL or CDN and have fewer cache invalidation issues. But sometimes, this is unexpected and you might want the original name instead:
 
-To disable the content hash, pass `--asset-naming` to `bun build --compile` like this:
-
-```bash terminal icon="terminal"
-bun build --compile --asset-naming="[name].[ext]" ./index.ts
-```
+To disable the content hash, configure asset naming:
+
+<Tabs>
+  <Tab title="CLI">
+    ```bash terminal icon="terminal"
+    bun build --compile --asset-naming="[name].[ext]" ./index.ts
+    ```
+  </Tab>
+  <Tab title="JavaScript">
+    ```ts build.ts icon="/icons/typescript.svg"
+    await Bun.build({
+      entrypoints: ["./index.ts"],
+      compile: {
+        outfile: "./myapp",
+      },
+      naming: {
+        asset: "[name].[ext]",
+      },
+    });
+    ```
+  </Tab>
+</Tabs>
 
 ---
 
 ## Minification
 
-To trim down the size of the executable a little, pass `--minify` to `bun build --compile`. This uses Bun's minifier to reduce the code size. Overall though, Bun's binary is still way too big and we need to make it smaller.
+To trim down the size of the executable, enable minification:
+
+<Tabs>
+  <Tab title="CLI">
+    ```bash terminal icon="terminal"
+    bun build --compile --minify ./index.ts --outfile myapp
+    ```
+  </Tab>
+  <Tab title="JavaScript">
+    ```ts build.ts icon="/icons/typescript.svg"
+    await Bun.build({
+      entrypoints: ["./index.ts"],
+      compile: {
+        outfile: "./myapp",
+      },
+      minify: true, // Enable all minification
+    });
+
+    // Or granular control:
+    await Bun.build({
+      entrypoints: ["./index.ts"],
+      compile: {
+        outfile: "./myapp",
+      },
+      minify: {
+        whitespace: true,
+        syntax: true,
+        identifiers: true,
+      },
+    });
+    ```
+
+  </Tab>
+</Tabs>
+
+This uses Bun's minifier to reduce the code size. Overall though, Bun's binary is still way too big and we need to make it smaller.
 
 ---
 
 ## Windows-specific flags
 
-When compiling a standalone executable on Windows, there are two platform-specific options that can be used to customize metadata on the generated `.exe` file:
-
-- `--windows-icon=path/to/icon.ico` to customize the executable file icon.
-- `--windows-hide-console` to disable the background terminal, which can be used for applications that do not need a TTY.
+When compiling a standalone executable on Windows, there are platform-specific options to customize metadata on the generated `.exe` file:
+
+<Tabs>
+  <Tab title="CLI">
+    ```bash terminal icon="terminal"
+    # Custom icon
+    bun build --compile --windows-icon=path/to/icon.ico ./app.ts --outfile myapp
+
+    # Hide console window (for GUI apps)
+    bun build --compile --windows-hide-console ./app.ts --outfile myapp
+    ```
+
+  </Tab>
+  <Tab title="JavaScript">
+    ```ts build.ts icon="/icons/typescript.svg"
+    await Bun.build({
+      entrypoints: ["./app.ts"],
+      compile: {
+        outfile: "./myapp",
+        windows: {
+          icon: "./path/to/icon.ico",
+          hideConsole: true,
+          // Additional Windows metadata:
+          title: "My Application",
+          publisher: "My Company",
+          version: "1.0.0",
+          description: "A standalone Windows application",
+          copyright: "Copyright 2024",
+        },
+      },
+    });
+    ```
+  </Tab>
+</Tabs>
+
+Available Windows options:
+
+- `icon` - Path to `.ico` file for the executable icon
+- `hideConsole` - Disable the background terminal (for GUI apps)
+- `title` - Application title in file properties
+- `publisher` - Publisher name in file properties
+- `version` - Version string in file properties
+- `description` - Description in file properties
+- `copyright` - Copyright notice in file properties
 
 <Warning>These flags currently cannot be used when cross-compiling because they depend on Windows APIs.</Warning>
 
@@ -571,9 +1075,23 @@ codesign -vvv --verify ./myapp
 
 Standalone executables support code splitting. Use `--compile` with `--splitting` to create an executable that loads code-split chunks at runtime.
 
-```bash
-bun build --compile --splitting ./src/entry.ts --outdir ./build
-```
+<Tabs>
+  <Tab title="CLI">
+    ```bash terminal icon="terminal"
+    bun build --compile --splitting ./src/entry.ts --outdir ./build
+    ```
+  </Tab>
+  <Tab title="JavaScript">
+    ```ts build.ts icon="/icons/typescript.svg"
+    await Bun.build({
+      entrypoints: ["./src/entry.ts"],
+      compile: true,
+      splitting: true,
+      outdir: "./build",
+    });
+    ```
+  </Tab>
+</Tabs>
 
 <CodeGroup>
 
@@ -602,6 +1120,50 @@ Lazy module loaded
 
 ---
 
+## Using plugins
+
+Plugins work with standalone executables, allowing you to transform files during the build process:
+
+```ts build.ts icon="/icons/typescript.svg"
+import type { BunPlugin } from "bun";
+
+const envPlugin: BunPlugin = {
+  name: "env-loader",
+  setup(build) {
+    build.onLoad({ filter: /\.env\.json$/ }, async args => {
+      // Transform .env.json files into validated config objects
+      const env = await Bun.file(args.path).json();
+
+      return {
+        contents: `export default ${JSON.stringify(env)};`,
+        loader: "js",
+      };
+    });
+  },
+};
+
+await Bun.build({
+  entrypoints: ["./cli.ts"],
+  compile: {
+    outfile: "./mycli",
+  },
+  plugins: [envPlugin],
+});
+```
+
+Example use case - embedding environment config at build time:
+
+```ts cli.ts icon="/icons/typescript.svg"
+import config from "./config.env.json";
+
+console.log(`Running in ${config.environment} mode`);
+console.log(`API endpoint: ${config.apiUrl}`);
+```
+
+Plugins can perform any transformation: compile YAML/TOML configs, inline SQL queries, generate type-safe API clients, or preprocess templates. Refer to the [plugin documentation](/docs/bundler/plugins) for more details.
+
+---
+
 ## Unsupported CLI arguments
 
 Currently, the `--compile` flag can only accept a single entrypoint at a time and does not support the following flags:
@@ -610,3 +1172,106 @@ Currently, the `--compile` flag can only accept a single entrypoint at a time an
 - `--public-path`
 - `--target=node` or `--target=browser`
 - `--no-bundle` - we always bundle everything into the executable.
+
+---
+
+## API reference
+
+The `compile` option in `Bun.build()` accepts three forms:
+
+```ts title="types" icon="/icons/typescript.svg"
+interface BuildConfig {
+  entrypoints: string[];
+  compile: boolean | Bun.Build.Target | CompileBuildOptions;
+  // ... other BuildConfig options (minify, sourcemap, define, plugins, etc.)
+}
+
+interface CompileBuildOptions {
+  target?: Bun.Build.Target; // Cross-compilation target
+  outfile?: string; // Output executable path
+  execArgv?: string[]; // Runtime arguments (process.execArgv)
+  autoloadTsconfig?: boolean; // Load tsconfig.json (default: false)
+  autoloadPackageJson?: boolean; // Load package.json (default: false)
+  autoloadDotenv?: boolean; // Load .env files (default: true)
+  autoloadBunfig?: boolean; // Load bunfig.toml (default: true)
+  windows?: {
+    icon?: string; // Path to .ico file
+    hideConsole?: boolean; // Hide console window
+    title?: string; // Application title
+    publisher?: string; // Publisher name
+    version?: string; // Version string
+    description?: string; // Description
+    copyright?: string; // Copyright notice
+  };
+}
+```
+
+Usage forms:
+
+```ts icon="/icons/typescript.svg"
+// Simple boolean - compile for current platform (uses entrypoint name as output)
+compile: true
+
+// Target string - cross-compile (uses entrypoint name as output)
+compile: "bun-linux-x64"
+
+// Full options object - specify outfile and other options
+compile: {
+  target: "bun-linux-x64",
+  outfile: "./myapp",
+}
+```
+
+### Supported targets
+
+```ts title="Bun.Build.Target" icon="/icons/typescript.svg"
+type Target =
+  | "bun-darwin-x64"
+  | "bun-darwin-x64-baseline"
+  | "bun-darwin-arm64"
+  | "bun-linux-x64"
+  | "bun-linux-x64-baseline"
+  | "bun-linux-x64-modern"
+  | "bun-linux-arm64"
+  | "bun-linux-x64-musl"
+  | "bun-linux-arm64-musl"
+  | "bun-windows-x64"
+  | "bun-windows-x64-baseline"
+  | "bun-windows-x64-modern";
+```
+
+### Complete example
+
+```ts build.ts icon="/icons/typescript.svg"
+import type { BunPlugin } from "bun";
+
+const myPlugin: BunPlugin = {
+  name: "my-plugin",
+  setup(build) {
+    // Plugin implementation
+  },
+};
+
+const result = await Bun.build({
+  entrypoints: ["./src/cli.ts"],
+  compile: {
+    target: "bun-linux-x64",
+    outfile: "./dist/mycli",
+    execArgv: ["--smol"],
+    autoloadDotenv: false,
+    autoloadBunfig: false,
+  },
+  minify: true,
+  sourcemap: "linked",
+  bytecode: true,
+  define: {
+    "process.env.NODE_ENV": JSON.stringify("production"),
+    VERSION: JSON.stringify("1.0.0"),
+  },
+  plugins: [myPlugin],
+});
+
+if (result.success) {
+  console.log("Build successful:", result.outputs[0].path);
+}
+```