bun-types 1.3.2-canary.20251105T140650 → 1.3.2

package/docs/bundler/{executables.md → executables.mdx}

@@ -1,33 +1,43 @@
+---
+title: "Single-file executable"
+description: "Generate standalone executables from TypeScript or JavaScript files with Bun"
+---
+
 Bun's bundler implements a `--compile` flag for generating a standalone binary from a TypeScript or JavaScript file.
 
-{% codetabs %}
+<CodeGroup>
 
-```bash
-$ bun build ./cli.ts --compile --outfile mycli
+```bash terminal icon="terminal"
+bun build ./cli.ts --compile --outfile mycli
 ```
 
-```ts#cli.ts
+```ts cli.ts icon="/icons/typescript.svg"
 console.log("Hello world!");
 ```
 
-{% /codetabs %}
+</CodeGroup>
 
 This bundles `cli.ts` into an executable that can be executed directly:
 
+```bash terminal icon="terminal"
+./mycli
 ```
-$ ./mycli
+
+```txt
 Hello world!
 ```
 
 All imported files and packages are bundled into the executable, along with a copy of the Bun runtime. All built-in Bun and Node.js APIs are supported.
 
+---
+
 ## Cross-compile to other platforms
 
 The `--target` flag lets you compile your standalone executable for a different operating system, architecture, or version of Bun than the machine you're running `bun build` on.
 
 To build for Linux x64 (most servers):
 
-```sh
+```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)
@@ -40,14 +50,14 @@ bun build --compile --target=bun-linux-x64-modern ./index.ts --outfile myapp
 
 To build for Linux ARM64 (e.g. Graviton or Raspberry Pi):
 
-```sh
+```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
 ```
 
 To build for Windows x64:
 
-```sh
+```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)
@@ -61,17 +71,17 @@ bun build --compile --target=bun-windows-x64-modern ./path/to/my/app.ts --outfil
 
 To build for macOS arm64:
 
-```sh
+```bash icon="terminal" terminal
 bun build --compile --target=bun-darwin-arm64 ./path/to/my/app.ts --outfile myapp
 ```
 
 To build for macOS x64:
 
-```sh
+```bash icon="terminal" terminal
 bun build --compile --target=bun-darwin-x64 ./path/to/my/app.ts --outfile myapp
 ```
 
-#### Supported targets
+### Supported targets
 
 The order of the `--target` flag does not matter, as long as they're delimited by a `-`.
 
@@ -86,21 +96,32 @@ The order of the `--target` flag does not matter, as long as they're delimited b
 | bun-linux-x64-musl    | Linux            | x64          | ✅     | ✅       | musl  |
 | bun-linux-arm64-musl  | Linux            | arm64        | ✅     | N/A      | musl  |
 
-On x64 platforms, Bun uses SIMD optimizations which require a modern CPU supporting AVX2 instructions. The `-baseline` build of Bun is for older CPUs that don't support these optimizations. Normally, when you install Bun we automatically detect which version to use but this can be harder to do when cross-compiling since you might not know the target CPU. You usually don't need to worry about it on Darwin x64, but it is relevant for Windows x64 and Linux x64. If you or your users see `"Illegal instruction"` errors, you might need to use the baseline version.
+<Warning>
+  On x64 platforms, Bun uses SIMD optimizations which require a modern CPU supporting AVX2 instructions. The `-baseline`
+  build of Bun is for older CPUs that don't support these optimizations. Normally, when you install Bun we automatically
+  detect which version to use but this can be harder to do when cross-compiling since you might not know the target CPU.
+  You usually don't need to worry about it on Darwin x64, but it is relevant for Windows x64 and Linux x64. If you or
+  your users see `"Illegal instruction"` errors, you might need to use the baseline version.
+</Warning>
+
+---
 
 ## Build-time constants
 
 Use the `--define` flag to inject build-time constants into your executable, such as version numbers, build timestamps, or configuration values:
 
-```bash
-$ bun build --compile --define BUILD_VERSION='"1.2.3"' --define BUILD_TIME='"2024-01-15T10:30:00Z"' src/cli.ts --outfile mycli
+```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
 ```
 
 These constants are embedded directly into your compiled binary at build time, providing zero runtime overhead and enabling dead code elimination optimizations.
 
-{% callout type="info" %}
-For comprehensive examples and advanced patterns, see the [Build-time constants guide](/guides/runtime/build-time-constants).
-{% /callout %}
+<Note>
+  For comprehensive examples and advanced patterns, see the [Build-time constants
+  guide](https://bun.com/guides/runtime/build-time-constants).
+</Note>
+
+---
 
 ## Deploying to production
 
@@ -112,7 +133,7 @@ With compiled executables, you can move that cost from runtime to build-time.
 
 When deploying to production, we recommend the following:
 
-```sh
+```bash icon="terminal" terminal
 bun build --compile --minify --sourcemap ./path/to/my/app.ts --outfile myapp
 ```
 
@@ -120,17 +141,22 @@ bun build --compile --minify --sourcemap ./path/to/my/app.ts --outfile myapp
 
 To improve startup time, enable bytecode compilation:
 
-```sh
+```bash icon="terminal" terminal
 bun build --compile --minify --sourcemap --bytecode ./path/to/my/app.ts --outfile myapp
 ```
 
 Using bytecode compilation, `tsc` starts 2x faster:
 
-{% image src="https://github.com/user-attachments/assets/dc8913db-01d2-48f8-a8ef-ac4e984f9763" width="689" /%}
+<Frame>
+  ![Bytecode performance comparison](https://github.com/user-attachments/assets/dc8913db-01d2-48f8-a8ef-ac4e984f9763)
+</Frame>
 
 Bytecode compilation moves parsing overhead for large input files from runtime to bundle time. Your app starts faster, in exchange for making the `bun build` command a little slower. It doesn't obscure source code.
 
-**Experimental:** Bytecode compilation is an experimental feature introduced in Bun v1.1.30. Only `cjs` format is supported (which means no top-level-await). Let us know if you run into any issues!
+<Warning>
+  **Experimental:** Bytecode compilation is an experimental feature introduced in Bun v1.1.30. Only `cjs` format is
+  supported (which means no top-level-await). Let us know if you run into any issues!
+</Warning>
 
 ### What do these flags do?
 
@@ -140,68 +166,77 @@ The `--sourcemap` argument embeds a sourcemap compressed with zstd, so that erro
 
 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.
 
+---
+
 ## Embedding runtime arguments
 
 **`--compile-exec-argv="args"`** - Embed runtime arguments that are available via `process.execArgv`:
 
-```bash
+```bash icon="terminal" terminal
 bun build --compile --compile-exec-argv="--smol --user-agent=MyBot" ./app.ts --outfile myapp
 ```
 
-```js
+```ts app.ts icon="/icons/typescript.svg"
 // In the compiled app
 console.log(process.execArgv); // ["--smol", "--user-agent=MyBot"]
 ```
 
-## Act as the Bun CLI
-
-{% note %}
+---
 
-New in Bun v1.2.16
+## Act as the Bun CLI
 
-{% /note %}
+<Note>New in Bun v1.2.16</Note>
 
 You can run a standalone executable as if it were the `bun` CLI itself by setting the `BUN_BE_BUN=1` environment variable. When this variable is set, the executable will ignore its bundled entrypoint and instead expose all the features of Bun's CLI.
 
 For example, consider an executable compiled from a simple script:
 
-```sh
-$ cat such-bun.js
-console.log("you shouldn't see this");
+```bash icon="terminal" terminal
+echo "console.log(\"you shouldn't see this\");" > such-bun.js
+bun build --compile ./such-bun.js
+```
 
-$ bun build --compile ./such-bun.js
- [3ms] bundle 1 modules
+```txt
+[3ms] bundle 1 modules
 [89ms] compile such-bun
 ```
 
-Normally, running `./such-bun` with arguments would execute the script. However, with the `BUN_BE_BUN=1` environment variable, it acts just like the `bun` binary:
+Normally, running `./such-bun` with arguments would execute the script.
 
-```sh
+```bash icon="terminal" terminal
 # Executable runs its own entrypoint by default
-$ ./such-bun install
+./such-bun install
+```
+
+```txt
 you shouldn't see this
+```
+
+However, with the `BUN_BE_BUN=1` environment variable, it acts just like the `bun` binary:
 
+```bash icon="terminal" terminal
 # With the env var, the executable acts like the `bun` CLI
-$ BUN_BE_BUN=1 ./such-bun install
+bun_BE_BUN=1 ./such-bun install
+```
+
+```txt
 bun install v1.2.16-canary.1 (1d1db811)
 Checked 63 installs across 64 packages (no changes) [5.00ms]
 ```
 
 This is useful for building CLI tools on top of Bun that may need to install packages, bundle dependencies, run different or local files and more without needing to download a separate binary or install bun.
 
-## Full-stack executables
-
-{% note %}
+---
 
-New in Bun v1.2.17
+## Full-stack executables
 
-{% /note %}
+<Note>New in Bun v1.2.17</Note>
 
 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.
 
-{% codetabs %}
+<CodeGroup>
 
-```ts#server.ts
+```ts server.ts icon="/icons/typescript.svg"
 import { serve } from "bun";
 import index from "./index.html";
 
@@ -215,12 +250,12 @@ const server = serve({
 console.log(`Server running at http://localhost:${server.port}`);
 ```
 
-```html#index.html
+```html index.html icon="file-code"
 <!DOCTYPE html>
 <html>
   <head>
     <title>My App</title>
-    <link rel="stylesheet" href="./styles.css">
+    <link rel="stylesheet" href="./styles.css" />
   </head>
   <body>
     <h1>Hello World</h1>
@@ -229,21 +264,21 @@ console.log(`Server running at http://localhost:${server.port}`);
 </html>
 ```
 
-```js#app.js
+```ts app.js icon="file-code"
 console.log("Hello from the client!");
 ```
 
-```css#styles.css
+```css styles.css icon="file-code"
 body {
   background-color: #f0f0f0;
 }
 ```
 
-{% /codetabs %}
+</CodeGroup>
 
 To build this into a single executable:
 
-```sh
+```bash terminal icon="terminal"
 bun build --compile ./server.ts --outfile myapp
 ```
 
@@ -256,25 +291,27 @@ This creates a self-contained binary that includes:
 
 The result is a single file that can be deployed anywhere without needing Node.js, Bun, or any dependencies installed. Just run:
 
-```sh
+```bash terminal icon="terminal"
 ./myapp
 ```
 
 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.
 
-For more details on building full-stack applications with Bun, see the [full-stack guide](/docs/bundler/fullstack).
+For more details on building full-stack applications with Bun, see the [full-stack guide](/bundler/fullstack).
+
+---
 
 ## Worker
 
 To use workers in a standalone executable, add the worker's entrypoint to the CLI arguments:
 
-```sh
-$ bun build --compile ./index.ts ./my-worker.ts --outfile myapp
+```bash terminal icon="terminal"
+bun build --compile ./index.ts ./my-worker.ts --outfile myapp
 ```
 
 Then, reference the worker in your code:
 
-```ts
+```ts index.ts icon="/icons/typescript.svg"
 console.log("Hello from Bun!");
 
 // Any of these will work:
@@ -289,13 +326,15 @@ In the future, we may automatically detect usages of statically-known paths in `
 
 If you use a relative path to a file not included in the standalone executable, it will attempt to load that path from disk relative to the current working directory of the process (and then error if it doesn't exist).
 
+---
+
 ## SQLite
 
 You can use `bun:sqlite` imports with `bun build --compile`.
 
 By default, the database is resolved relative to the current working directory of the process.
 
-```js
+```ts index.ts icon="/icons/typescript.svg"
 import db from "./my.db" with { type: "sqlite" };
 
 console.log(db.query("select * from users LIMIT 1").get());
@@ -303,18 +342,20 @@ console.log(db.query("select * from users LIMIT 1").get());
 
 That means if the executable is located at `/usr/bin/hello`, the user's terminal is located at `/home/me/Desktop`, it will look for `/home/me/Desktop/my.db`.
 
-```
-$ cd /home/me/Desktop
-$ ./hello
+```bash terminal icon="terminal"
+cd /home/me/Desktop
+./hello
 ```
 
+---
+
 ## Embed assets & files
 
 Standalone executables support embedding files.
 
 To embed files into an executable with `bun build --compile`, import the file in your code.
 
-```ts
+```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";
@@ -331,7 +372,7 @@ Embedded files can be read using `Bun.file`'s functions or the Node.js `fs.readF
 
 For example, to read the contents of the embedded file:
 
-```js
+```ts index.ts icon="/icons/typescript.svg"
 import icon from "./icon.png" with { type: "file" };
 import { file } from "bun";
 
@@ -344,7 +385,7 @@ const bytes = await file(icon).arrayBuffer();
 
 If your application wants to embed a SQLite database, set `type: "sqlite"` in the import attribute and the `embed` attribute to `"true"`.
 
-```js
+```ts index.ts icon="/icons/typescript.svg"
 import myEmbeddedDb from "./my.db" with { type: "sqlite", embed: "true" };
 
 console.log(myEmbeddedDb.query("select * from users LIMIT 1").get());
@@ -356,7 +397,7 @@ This database is read-write, but all changes are lost when the executable exits
 
 As of Bun v1.0.23, you can embed `.node` files into executables.
 
-```js
+```ts index.ts icon="/icons/typescript.svg"
 const addon = require("./addon.node");
 
 console.log(addon.hello());
@@ -368,13 +409,13 @@ Unfortunately, if you're using `@mapbox/node-pre-gyp` or other similar tools, yo
 
 To embed a directory with `bun build --compile`, use a shell glob in your `bun build` command:
 
-```sh
-$ bun build --compile ./index.ts ./public/**/*.png
+```bash terminal icon="terminal"
+bun build --compile ./index.ts ./public/**/*.png
 ```
 
 Then, you can reference the files in your code:
 
-```ts
+```ts index.ts icon="/icons/typescript.svg"
 import icon from "./public/assets/icon.png" with { type: "file" };
 import { file } from "bun";
 
@@ -392,7 +433,7 @@ This is honestly a workaround, and we expect to improve this in the future with
 
 To get a list of all embedded files, use `Bun.embeddedFiles`:
 
-```js
+```ts index.ts icon="/icons/typescript.svg"
 import "./icon.png" with { type: "file" };
 import { embeddedFiles } from "bun";
 
@@ -413,141 +454,40 @@ By default, embedded files have a content hash appended to their name. This is u
 
 To disable the content hash, pass `--asset-naming` to `bun build --compile` like this:
 
-```sh
-$ bun build --compile --asset-naming="[name].[ext]" ./index.ts
+```bash terminal icon="terminal"
+bun build --compile --asset-naming="[name].[ext]" ./index.ts
 ```
 
+---
+
 ## 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.
 
-## Using Bun.build() API
-
-You can also generate standalone executables using the `Bun.build()` JavaScript API. This is useful when you need programmatic control over the build process.
-
-### Basic usage
-
-```js
-await Bun.build({
-  entrypoints: ["./app.ts"],
-  outdir: "./dist",
-  compile: {
-    target: "bun-windows-x64",
-    outfile: "myapp.exe",
-  },
-});
-```
-
-### Windows metadata with Bun.build()
-
-When targeting Windows, you can specify metadata through the `windows` object:
-
-```js
-await Bun.build({
-  entrypoints: ["./app.ts"],
-  outdir: "./dist",
-  compile: {
-    target: "bun-windows-x64",
-    outfile: "myapp.exe",
-    windows: {
-      title: "My Application",
-      publisher: "My Company Inc",
-      version: "1.2.3.4",
-      description: "A powerful application built with Bun",
-      copyright: "© 2024 My Company Inc",
-      hideConsole: false, // Set to true for GUI applications
-      icon: "./icon.ico", // Path to icon file
-    },
-  },
-});
-```
-
-### Cross-compilation with Bun.build()
-
-You can cross-compile for different platforms:
-
-```js
-// Build for multiple platforms
-const platforms = [
-  { target: "bun-windows-x64", outfile: "app-windows.exe" },
-  { target: "bun-linux-x64", outfile: "app-linux" },
-  { target: "bun-darwin-arm64", outfile: "app-macos" },
-];
-
-for (const platform of platforms) {
-  await Bun.build({
-    entrypoints: ["./app.ts"],
-    outdir: "./dist",
-    compile: platform,
-  });
-}
-```
+---
 
 ## Windows-specific flags
 
-When compiling a standalone executable for Windows, there are several platform-specific options that can be used to customize the generated `.exe` file:
-
-### Visual customization
-
-- `--windows-icon=path/to/icon.ico` - Set the executable file icon
-- `--windows-hide-console` - Disable the background terminal window (useful for GUI applications)
-
-### Metadata customization
-
-You can embed version information and other metadata into your Windows executable:
-
-- `--windows-title <STR>` - Set the product name (appears in file properties)
-- `--windows-publisher <STR>` - Set the company name
-- `--windows-version <STR>` - Set the version number (e.g. "1.2.3.4")
-- `--windows-description <STR>` - Set the file description
-- `--windows-copyright <STR>` - Set the copyright information
-
-#### Example with all metadata flags:
-
-```sh
-bun build --compile ./app.ts \
-  --outfile myapp.exe \
-  --windows-title "My Application" \
-  --windows-publisher "My Company Inc" \
-  --windows-version "1.2.3.4" \
-  --windows-description "A powerful application built with Bun" \
-  --windows-copyright "© 2024 My Company Inc"
-```
-
-This metadata will be visible in Windows Explorer when viewing the file properties:
-
-1. Right-click the executable in Windows Explorer
-2. Select "Properties"
-3. Go to the "Details" tab
-
-#### Version string format
+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:
 
-The `--windows-version` flag accepts version strings in the following formats:
+- `--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.
 
-- `"1"` - Will be normalized to "1.0.0.0"
-- `"1.2"` - Will be normalized to "1.2.0.0"
-- `"1.2.3"` - Will be normalized to "1.2.3.0"
-- `"1.2.3.4"` - Full version format
+<Warning>These flags currently cannot be used when cross-compiling because they depend on Windows APIs.</Warning>
 
-Each version component must be a number between 0 and 65535.
-
-{% callout %}
-
-These flags currently cannot be used when cross-compiling because they depend on Windows APIs. They are only available when building on Windows itself.
-
-{% /callout %}
+---
 
 ## Code signing on macOS
 
 To codesign a standalone executable on macOS (which fixes Gatekeeper warnings), use the `codesign` command.
 
-```sh
-$ codesign --deep --force -vvvv --sign "XXXXXXXXXX" ./myapp
+```bash terminal icon="terminal"
+codesign --deep --force -vvvv --sign "XXXXXXXXXX" ./myapp
 ```
 
 We recommend including an `entitlements.plist` file with JIT permissions.
 
-```xml#entitlements.plist
+```xml icon="xml" title="info.plist"
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -568,59 +508,28 @@ We recommend including an `entitlements.plist` file with JIT permissions.
 
 To codesign with JIT support, pass the `--entitlements` flag to `codesign`.
 
-```sh
-$ codesign --deep --force -vvvv --sign "XXXXXXXXXX" --entitlements entitlements.plist ./myapp
+```bash terminal icon="terminal"
+codesign --deep --force -vvvv --sign "XXXXXXXXXX" --entitlements entitlements.plist ./myapp
 ```
 
 After codesigning, verify the executable:
 
-```sh
-$ codesign -vvv --verify ./myapp
+```bash terminal icon="terminal"
+codesign -vvv --verify ./myapp
 ./myapp: valid on disk
 ./myapp: satisfies its Designated Requirement
 ```
 
-{% callout %}
-
-Codesign support requires Bun v1.2.4 or newer.
-
-{% /callout %}
-
-## Code splitting
-
-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
-```
+<Warning>Codesign support requires Bun v1.2.4 or newer.</Warning>
 
-{% codetabs %}
-
-```ts#src/entry.ts
-console.log("Entrypoint loaded");
-const lazy = await import("./lazy.ts");
-lazy.hello();
-```
-
-```ts#src/lazy.ts
-export function hello() {
-  console.log("Lazy module loaded");
-}
-```
-
-{% /codetabs %}
-
-```bash
-$ ./build/entry
-Entrypoint loaded
-Lazy module loaded
-```
+---
 
 ## Unsupported CLI arguments
 
 Currently, the `--compile` flag can only accept a single entrypoint at a time and does not support the following flags:
 
-- `--outdir` — use `outfile` instead (except when using with `--splitting`).
+- `--outdir` — use `outfile` instead.
+- `--splitting`
 - `--public-path`
 - `--target=node` or `--target=browser`
 - `--no-bundle` - we always bundle everything into the executable.