interface
CompileBuildOptions
interface CompileBuildOptions
- allowCodeFromDisk?: boolean
With
aot: let a dynamicimport(),require()ornew Worker()load code that isn't in the executable from disk when the program runs, such as a plugin or a config file. Bun interprets that code.Without it, the executable only runs code that was compiled into it, and such a load throws. The option keeps Bun's transpiler and the source code of Bun's built-in modules in the executable, and the compiler can prove less about the program, so the executable is larger and can run slower.
Equivalent CLI flag:
--aot-allow-code-from-disk - aot?: boolean
Compile the program's JavaScript and TypeScript to machine code at build time. It cannot be combined with
bytecode.The executable has no JIT. Code that only exists at run time, such as a string passed to
eval()ornew Function(), runs in the interpreter.Built-in objects such as
Object.prototype,Array.prototypeandPromiseare read-only in the executable. Assigning to one throws aTypeError. Breakpoints aren't available.Requires a
targetthat matches the platform and Bun version running the build.formathas no effect: each file keeps the module format it is written in.Equivalent CLI flag:
--aot - aotExplain?: AotReport | AotReport[]
With
aot: reports to add toBuildOutput.logs, at level"verbose"."text": the code that compiled to a slow path, one entry per cause with a fix, worst first"json": the same, one JSON object per line"guards": every type guard that can fail at run time, why the compiler couldn't remove it, and how to fix it"guards-json": the same, one JSON object per line"trim": which Bun and Node.js APIs the program uses, and whytrimkept or removed each feature"allocations": where each object is allocated (stack, heap or removed), and why"forms": how many operations of each kind compiled to inline code, to a call of shared code, or to a call into the runtime"statistics": what the build counted, one name and number per line
Equivalent CLI flag:
--explain - aotHarden?: string | string[]
With
aot: add run-time checks, so that a bug in the compiler is harder to turn into a memory bug. Each name costs speed, and none is on unless it is listed here."proof-checks": check the type that the compiler has proven of a value again at each read, and check again what the compiler remembers from earlier code. Objects stay on the heap, not on the stack. The build also runs the compiler's own verifier."ignore-told-ranges": check every index against the length, where the index is used.
A check that fails aborts the process.
Takes a list of names, or one string with commas between the names.
Bun.buildthrows on a name that it doesn't know.Equivalent CLI flag:
--aot-harden - aotOrder?: null | string | false | string[]
Lay the executable out by the order in which a run of it entered its functions. Requires
aot: true.Run an executable built with
aotRecordOrder: truewithBUN_AOT_ORDER_OUT=<path>to record a start, then build again with that file. A file from an older build of the app still applies.With several files, list the most important one first. A function lies where the first file that lists it places it.
falseandnullmean no file, soaotOrder: haveProfile && pathworks.Equivalent CLI flag:
--aot-order <file>[,<file>...] - aotRecordOrder?: boolean
Build an executable that writes what
aotOrdertakes when it runs withBUN_AOT_ORDER_OUT=<path>. Other executables have no recorder. Requiresaot: true.Equivalent CLI flag:
--aot-record-order - assets?: string[]
Files or directories to embed into the executable under their original relative paths. At runtime they are reachable via
node:fsandBun.file()relative toimport.meta.dir.Equivalent CLI flag:
--asset(repeatable) - autoloadBunfig?: boolean
Whether the standalone executable loads bunfig.toml when it runs
Equivalent CLI flags:
--compile-autoload-bunfig,--no-compile-autoload-bunfig - autoloadDotenv?: boolean
Whether the standalone executable loads .env files when it runs
Equivalent CLI flags:
--compile-autoload-dotenv,--no-compile-autoload-dotenv - autoloadPackageJson?: boolean
Whether the standalone executable loads package.json when it runs
Equivalent CLI flags:
--compile-autoload-package-json,--no-compile-autoload-package-json - autoloadTsconfig?: boolean
Whether the standalone executable loads tsconfig.json when it runs
Equivalent CLI flags:
--compile-autoload-tsconfig,--no-compile-autoload-tsconfig - bytecodeOrder?: null | string | false | string[]
Profile-guided layout for the executable's bytecode. Requires
bytecode: true.Run an executable built with
bytecode: truewithBUN_BYTECODE_ORDER_OUT=<path>to record which functions it uses, then build again with that file. Bun places the bytecode the run used together at the front, so the executable starts faster and uses less memory. A profile from an older build of the app still applies.With several files, list the most common way of starting the app first.
falseandnullmean no profile, sobytecodeOrder: haveProfile && pathworks.Equivalent CLI flag:
--bytecode-order <file>[,<file>...] - disallowCodeGenerationFromStrings?: boolean | 'strict'
In the executable,
eval()and theFunctionconstructors throw anEvalError, as with Node.js's--disallow-code-generation-from-strings."strict"also blocks every other way to run code from a string.Equivalent CLI flag:
--disallow-code-generation-from-strings - functionSource?: boolean
With
aot: embed each function's source code in the executable.With
false,fn.toString()returnsfunction name() { [native code] }and the executable is smaller.--preloadinBUN_OPTIONSis an error at startup, withinspectortoo.obfuscateandsourcemap: "external"implyfalse.Equivalent CLI flag:
--no-compile-function-source - inspector?: boolean
With
aot: let a debugger attach to the executable throughBUN_INSPECT, or--inspect,--inspect-waitand--inspect-brkinBUN_OPTIONS.A debugger can run any code in any scope, so the compiler can prove less about the program. The executable is larger and slower.
Equivalent CLI flag:
--compile-inspector - jitPolicy?: number
The JIT policy the executable starts with (see Bun.unsafe.setJITPolicy).
1is the normal policy. A value> 1multiplies JavaScriptCore's tier-up thresholds so code that only runs during startup stays in the interpreter longer; the app should callBun.unsafe.setJITPolicy(1)once it is interactive.Equivalent CLI flag:
--compile-jit-policy <n> - obfuscate?: boolean
With
aot: strip function names and file names from the executable and write a source map next to it.sourcemap: "external"does the same for stack traces and leaves thenameof functions and classes alone. Withobfuscateit is"".Equivalent CLI flag:
--obfuscate - trim?: boolean | TrimOptions
Remove the Bun and Node.js APIs your code never calls from the executable.
With
aot, the compiler knows which APIs the program uses, and Bun removes every other feature. Withoutaot, Bun only removes the command-line tools. An object does whattruedoes, with the options in TrimOptions.Removing a feature removes its code, not its names: every global, constructor, prototype, property and constant is still there. A call, a
new, a getter or a setter of a removed feature throws anErrorwhose message has the API's name and whosecodeis"ERR_FEATURE_REMOVED". Importing a removed built-in module, such asbun:sqlite, throws anErrorwhosecodeis"ERR_MODULE_NOT_FOUND". If code reaches a removed feature any other way, the process prints the feature and exits with code 70.The build fails if
allowhas an unknown name, orlocaleshas a locale that Bun has no data for.Equivalent CLI flag:
--trimawait Bun.build({ entrypoints: ["./server.ts"], compile: { outfile: "./server", aot: true, trim: { allow: ["sqlite"], locales: ["en"] } }, }); - windows?: { copyright: string; description: string; hideConsole: boolean; icon: string; publisher: string; title: string; version: string }