Single-file executable - BunDocumentation Index
Fetch the complete documentation index at: /docs/llms.txt
Use this file to discover all available pages before exploring further.
Skip to main contentBun home pageGenerate standalone executables from TypeScript or JavaScript files with Bun
bun build ./cli.ts --compile --outfile mycli:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0 hidden" data-component-part="tab-content">build.ts
await Bun.build({
entrypoints: ["./cli.ts"],
compile: {
outfile: "./mycli",
},
});
cli.tsconsole.log("Hello world!");
This bundles cli.ts into an executable that can be executed directly:
terminal./mycli
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): CLI JavaScript:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0" data-component-part="tab-content">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:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0 hidden" data-component-part="tab-content">build.ts
// 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",
},
});
To build for Linux ARM64 (e.g. Graviton or Raspberry Pi):
CLI JavaScript:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0" data-component-part="tab-content">terminal# Note: the default architecture is x64 if no architecture is specified. bun build --compile --target=bun-linux-arm64 ./index.ts --outfile myapp:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0 hidden" data-component-part="tab-content">build.ts
await Bun.build({
entrypoints: ["./index.ts"],
compile: {
target: "bun-linux-arm64",
outfile: "./myapp",
},
});
To build for Windows x64:
CLI JavaScript:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0" data-component-part="tab-content">terminalbun 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:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0 hidden" data-component-part="tab-content">build.ts
// 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",
},
});
To build for Windows arm64:
CLI JavaScript:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0" data-component-part="tab-content">terminalbun build --compile --target=bun-windows-arm64 ./path/to/my/app.ts --outfile myapp # note: if no .exe extension is provided, Bun will automatically add it for Windows executables:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0 hidden" data-component-part="tab-content">build.ts
await Bun.build({
entrypoints: ["./path/to/my/app.ts"],
compile: {
target: "bun-windows-arm64",
outfile: "./myapp", // .exe added automatically
},
});
To build for macOS arm64:
CLI JavaScript:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0" data-component-part="tab-content">terminalbun build --compile --target=bun-darwin-arm64 ./path/to/my/app.ts --outfile myapp:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0 hidden" data-component-part="tab-content">build.ts
await Bun.build({
entrypoints: ["./path/to/my/app.ts"],
compile: {
target: "bun-darwin-arm64",
outfile: "./myapp",
},
});
To build for macOS x64:
CLI JavaScript:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0" data-component-part="tab-content">terminalbun build --compile --target=bun-darwin-x64 ./path/to/my/app.ts --outfile myapp:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0 hidden" data-component-part="tab-content">build.ts
await Bun.build({
entrypoints: ["./path/to/my/app.ts"],
compile: {
target: "bun-darwin-x64",
outfile: "./myapp",
},
});
Supported targets
The order of the --target flag does not matter, as long as they’re delimited by a -.
—targetOperating SystemArchitectureModernBaselineLibcbun-linux-x64Linuxx64✅✅glibcbun-linux-arm64Linuxarm64✅N/Aglibcbun-windows-x64Windowsx64✅✅-bun-windows-arm64Windowsarm64✅N/A-bun-darwin-x64macOSx64✅✅-bun-darwin-arm64macOSarm64✅N/A-bun-linux-x64-muslLinuxx64✅✅muslbun-linux-arm64-muslLinuxarm64✅N/Amusl
bun build --compile --define BUILD_VERSION='"1.2.3"' --define BUILD_TIME='"2024-01-15T10:30:00Z"' src/cli.ts --outfile mycli:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0 hidden" data-component-part="tab-content">build.ts
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"),
},
});
These constants are embedded directly into your compiled binary at build time, providing zero runtime overhead and enabling dead code elimination optimizations.
bun build --compile --minify --sourcemap ./path/to/my/app.ts --outfile myapp:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0 hidden" data-component-part="tab-content">build.ts
await Bun.build({
entrypoints: ["./path/to/my/app.ts"],
compile: {
outfile: "./myapp",
},
minify: true,
sourcemap: "linked",
});
Bytecode compilation
To improve startup time, enable bytecode compilation:
CLI JavaScript:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0" data-component-part="tab-content">terminalbun build --compile --minify --sourcemap --bytecode ./path/to/my/app.ts --outfile myapp:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0 hidden" data-component-part="tab-content">build.ts
await Bun.build({
entrypoints: ["./path/to/my/app.ts"],
compile: {
outfile: "./myapp",
},
minify: true,
sourcemap: "linked",
bytecode: true,
});
Using bytecode compilation, tsc starts 2x faster:
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.
bun build --compile --compile-exec-argv="--smol --user-agent=MyBot" ./app.ts --outfile myapp:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0 hidden" data-component-part="tab-content">build.ts
await Bun.build({
entrypoints: ["./app.ts"],
compile: {
execArgv: ["--smol", "--user-agent=MyBot"],
outfile: "./myapp",
},
});
app.ts// In the compiled app 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: 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" ./myappThis is useful for debugging or profiling production executables without rebuilding them. 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
# Enable runtime loading of tsconfig.json bun build --compile --compile-autoload-tsconfig ./app.ts --outfile myapp # Enable runtime loading of package.json bun build --compile --compile-autoload-package-json ./app.ts --outfile myapp # Enable both bun build --compile --compile-autoload-tsconfig --compile-autoload-package-json ./app.ts --outfile myappDisabling config loading at runtime To disable .env or bunfig.toml loading for deterministic execution: CLI JavaScript:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0" data-component-part="tab-content">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:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0 hidden" data-component-part="tab-content">build.ts
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",
},
});
Act as the Bun CLI
echo "console.log(\"you shouldn't see this\");" > such-bun.js bun build --compile ./such-bun.js
[3ms] bundle 1 modules [89ms] compile such-bunNormally, running ./such-bun with arguments would execute the script. terminal
# Executable runs its own entrypoint by default ./such-bun install
you shouldn't see thisHowever, with the BUN_BE_BUN=1 environment variable, it acts just like the bun binary: terminal
# With the env var, the executable acts like the `bun` CLI BUN_BE_BUN=1 ./such-bun install
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
import { serve } from "bun";
import index from "./index.html";
const server = serve({
routes: {
"/": index,
"/api/hello": { GET: () => Response.json({ message: "Hello from API" }) },
},
});
console.log(`Server running at http://localhost:${server.port}`);
To build this into a single executable:
CLI JavaScript:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0" data-component-part="tab-content">terminalbun build --compile ./server.ts --outfile myapp:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0 hidden" data-component-part="tab-content">build.ts
await Bun.build({
entrypoints: ["./server.ts"],
compile: {
outfile: "./myapp",
},
});
This creates a self-contained binary that includes:
Your server code
The Bun runtime
All frontend assets (HTML, CSS, JavaScript)
Any npm packages used by your server
The result is a single file that can be deployed anywhere without needing Node.js, Bun, or any dependencies installed. Just run:
terminal./myappBun 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. Worker To use workers in a standalone executable, add the worker’s entrypoint to the build: CLI JavaScript:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0" data-component-part="tab-content">terminal
bun build --compile ./index.ts ./my-worker.ts --outfile myapp:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0 hidden" data-component-part="tab-content">build.ts
await Bun.build({
entrypoints: ["./index.ts", "./my-worker.ts"],
compile: {
outfile: "./myapp",
},
});
Then, reference the worker in your code:
index.tsconsole.log("Hello from Bun!");
// Any of these will work:
new Worker("./my-worker.ts");
new Worker(new URL("./my-worker.ts", import.meta.url));
new Worker(new URL("./my-worker.ts", import.meta.url).href);
When you add multiple entrypoints to a standalone executable, they will be bundled separately into the executable.
In the future, we may automatically detect usages of statically-known paths in new Worker(path) and then bundle those into the executable, but for now, you’ll need to add it to the shell command manually like the above example.
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.
index.tsimport db from "./my.db" with { type: "sqlite" };
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.
terminalcd /home/me/Desktop ./helloEmbed assets & 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 to embed a file: index.ts
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:
Reads the file contents
Embeds the data into the executable
Replaces the import with an internal path (prefixed with $bunfs/)
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:
index.tsimport 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) {
return new Response(file(icon), {
headers: { "Content-Type": "image/png" },
});
},
};
Reading embedded files with Node.js fs
Embedded files work seamlessly with Node.js file system APIs:
index.tsimport 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
index.tsimport configPath from "./default-config.json" with { type: "file" };
import { file } from "bun";
// 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:
server.tsimport 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
index.tsimport 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
index.tsimport 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
If your application wants to embed a SQLite database into the compiled executable, set type: "sqlite" in the import attribute and the embed attribute to "true".
The database file must already exist on disk. Then, import it in your code:
index.tsimport myEmbeddedDb from "./my.db" with { type: "sqlite", embed: "true" };
console.log(myEmbeddedDb.query("select * from users LIMIT 1").get());
Finally, compile it into a standalone executable:
terminalbun build --compile ./index.ts --outfile mycli
const addon = require("./addon.node");
console.log(addon.hello());
Unfortunately, if you’re using @mapbox/node-pre-gyp or other similar tools, you’ll need to make sure the .node file is directly required or it won’t bundle correctly.
Embed directories
To embed a directory with bun build --compile, include file patterns in your build:
CLI JavaScript:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0" data-component-part="tab-content">terminalbun build --compile ./index.ts ./public/**/*.png:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0 hidden" data-component-part="tab-content">build.ts
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",
},
});
Then, you can reference the files in your code:
index.tsimport icon from "./public/assets/icon.png" with { type: "file" };
import { file } from "bun";
export default {
fetch(req) {
// Embedded files can be streamed from Response objects
return new Response(file(icon));
},
};
This is honestly a workaround, and we expect to improve this in the future with a more direct API.
Listing embedded files
Bun.embeddedFiles gives you access to all embedded files as Blob objects:
index.tsimport "./icon.png" with { type: "file" };
import "./data.json" with { type: "file" };
import "./template.html" with { type: "file" };
import { embeddedFiles } from "bun";
// 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
Each item in Bun.embeddedFiles is a Blob with a name property:
embeddedFiles: ReadonlyArrayBlob>;This is useful for dynamically serving all embedded assets using static routes: server.ts
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: Recordstring, 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 });
},
});
bun build --compile --asset-naming="[name].[ext]" ./index.ts:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0 hidden" data-component-part="tab-content">build.ts
await Bun.build({
entrypoints: ["./index.ts"],
compile: {
outfile: "./myapp",
},
naming: {
asset: "[name].[ext]",
},
});
Minification
To trim down the size of the executable, enable minification:
CLI JavaScript:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0" data-component-part="tab-content">terminalbun build --compile --minify ./index.ts --outfile myapp:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0 hidden" data-component-part="tab-content">build.ts
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,
},
});
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 platform-specific options to customize metadata on the generated .exe file:
CLI JavaScript:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0" data-component-part="tab-content">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:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0 hidden" data-component-part="tab-content">build.ts
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",
},
},
});
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
codesign --deep --force -vvvv --sign "XXXXXXXXXX" ./myappWe recommend including an entitlements.plist file with JIT permissions. info.plist
xml version="1.0" encoding="UTF-8"?> DOCTYPE plist PUBLIC "-http://Apple//DTD PLIST 1.0http://EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> plist version="1.0"> dict> key>com.apple.security.cs.allow-jitkey> true/> key>com.apple.security.cs.allow-unsigned-executable-memorykey> true/> key>com.apple.security.cs.disable-executable-page-protectionkey> true/> key>com.apple.security.cs.allow-dyld-environment-variableskey> true/> key>com.apple.security.cs.disable-library-validationkey> true/> dict> plist>To codesign with JIT support, pass the --entitlements flag to codesign. terminal
codesign --deep --force -vvvv --sign "XXXXXXXXXX" --entitlements entitlements.plist ./myappAfter codesigning, verify the executable: terminal
codesign -vvv --verify ./myapp ./myapp: valid on disk ./myapp: satisfies its Designated Requirement
bun build --compile --splitting ./src/entry.ts --outdir ./build:first-child:not(p)]:mt-0 [&>:first-child:not(p)_img]:mt-0 [&>:first-child[data-table-wrapper]]:!pt-0 hidden" data-component-part="tab-content">build.ts
await Bun.build({
entrypoints: ["./src/entry.ts"],
compile: true,
splitting: true,
outdir: "./build",
});
src/entry.tssrc/lazy.tsconsole.log("Entrypoint loaded");
const lazy = await import("./lazy.ts");
lazy.hello();
terminal./build/entry
Entrypoint loaded Lazy module loadedUsing plugins Plugins work with standalone executables, allowing you to transform files during the build process: build.ts
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:
cli.tsimport 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 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:
--outdir — use outfile instead (except when using with --splitting).
--public-path
--target=node
--target=browser (without HTML entrypoints — see Standalone HTML for --compile --target=browser with .html files)
--no-bundle - we always bundle everything into the executable.
API reference
The compile option in Bun.build() accepts three forms:
typesinterface 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:
// 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
Bun.Build.Targettype 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" | "bun-windows-arm64";Complete example build.ts
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);
}
Was this page helpful?
Single-file executable - Bun,AI智能索引,全网链接索引,智能导航,网页索引
- Generate standalone executables from TypeScript or JavaScript files with Bun