interface

CompileBuildOptions

interface CompileBuildOptions

  • allowCodeFromDisk?: boolean

    With aot: let a dynamic import(), require() or new 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() or new Function(), runs in the interpreter.

    Built-in objects such as Object.prototype, Array.prototype and Promise are read-only in the executable. Assigning to one throws a TypeError. Breakpoints aren't available.

    Requires a target that matches the platform and Bun version running the build. format has no effect: each file keeps the module format it is written in.

    Equivalent CLI flag: --aot

  • aotExplain?: AotReport | AotReport[]

    With aot: reports to add to BuildOutput.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 why trim kept 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.build throws 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: true with BUN_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.

    false and null mean no file, so aotOrder: haveProfile && path works.

    Equivalent CLI flag: --aot-order <file>[,<file>...]

  • aotRecordOrder?: boolean

    Build an executable that writes what aotOrder takes when it runs with BUN_AOT_ORDER_OUT=<path>. Other executables have no recorder. Requires aot: 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:fs and Bun.file() relative to import.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: true with BUN_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. false and null mean no profile, so bytecodeOrder: haveProfile && path works.

    Equivalent CLI flag: --bytecode-order <file>[,<file>...]

  • disallowCodeGenerationFromStrings?: boolean | 'strict'

    In the executable, eval() and the Function constructors throw an EvalError, 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

  • execArgv?: string[]
  • functionSource?: boolean

    With aot: embed each function's source code in the executable.

    With false, fn.toString() returns function name() { [native code] } and the executable is smaller. --preload in BUN_OPTIONS is an error at startup, with inspector too. obfuscate and sourcemap: "external" imply false.

    Equivalent CLI flag: --no-compile-function-source

  • inspector?: boolean

    With aot: let a debugger attach to the executable through BUN_INSPECT, or --inspect, --inspect-wait and --inspect-brk in BUN_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). 1 is the normal policy. A value > 1 multiplies JavaScriptCore's tier-up thresholds so code that only runs during startup stays in the interpreter longer; the app should call Bun.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 the name of functions and classes alone. With obfuscate it is "".

    Equivalent CLI flag: --obfuscate

  • outfile?: string
  • 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. Without aot, Bun only removes the command-line tools. An object does what true does, 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 an Error whose message has the API's name and whose code is "ERR_FEATURE_REMOVED". Importing a removed built-in module, such as bun:sqlite, throws an Error whose code is "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 allow has an unknown name, or locales has a locale that Bun has no data for.

    Equivalent CLI flag: --trim

    await 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 }