bun build --compile: Packaging JSC, Assets, and Code into a Single Binary
- Last updated
- Prerequisites:
- Bun.build bundler
- Operating system executable formats (ELF, Mach-O, PE)
- bun
- single-executable
- binary
- compilation
- cli
- deployment
Read at your depth
The practical view
`bun build --compile ./cli.ts --outfile my-tool` compiles your TypeScript/JavaScript application and all its dependencies into a standalone, single-file binary executable. The resulting binary runs on target machines without requiring Bun or Node.js to be installed. You can cross-compile for other operating systems via `--target` (e.g. `--target=bun-linux-x64`).
The same idea in other frameworks
Node.js Single Executable Applications (SEA) via `node --experimental-sea-config`.`deno compile --allow-all main.ts`.`bun build --compile ./src/index.ts --outfile my-app`.`go build -o my-app .` (native static compilation).Legacy vs modern
Node.js Container Deployment vs Bun Standalone Single Binary
Deploying Node requires shipping gigabytes of node_modules and runtime images; Bun compiles to a single 50MB standalone binary.
FROM node:20; COPY . .; RUN npm install; CMD ["node", "index.js"] // ❌ 1GB Containerbun build --compile ./server.ts --outfile /dist/server // ✅ NEW: Single static binaryInterview gotchas
Context
Interviewers test your knowledge of cross-compilation targets in `bun build --compile`.
The mechanical answer
Yes. Bun supports cross-compilation via the `--target` flag: `bun build --compile --target=bun-linux-x64 ./server.ts --outfile server-linux`. Bun downloads the pre-compiled standalone runtime skeleton for the target architecture and embeds your bundle into it.
Trap
Supported targets include `bun-linux-x64`, `bun-linux-arm64`, `bun-darwin-x64`, `bun-darwin-arm64`, and `bun-windows-x64`.
Context
Checks knowledge of Virtual File System (VFS) embedding in Bun binaries.
The mechanical answer
Yes. If your code references assets via `import icon from './icon.png' with { type: 'file' }` or `Bun.file('./schema.sql')`, Bun bundles the binary asset directly into the executable's embedded filesystem. At runtime, `Bun.file('./schema.sql')` reads directly from the embedded executable binary memory without needing external files on disk.
Trap
Dynamic path lookups like `fs.readFileSync(dynamicVariable)` cannot be statically analyzed for embedding; use explicit `with { type: 'file' }` or static path literals.