bun.CompileBuildOptions

interface CompileBuildOptions

• allowCodeFromDisk?: boolean

  With aot: let a dynamic import() or require() 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. bytecode has no effect with it.

  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 in strict mode and does nothing in sloppy mode. Breakpoints aren't available.

  Requires format: "esm" (the default with aot) and a target that matches the platform and Bun version running the build.

  Equivalent CLI flag: --aot

• aotDisable?: string | string[]

  With aot: build without some steps of the compiler. The program behaves the same. The executable can be larger and slower.

  When the compiler can't finish a build, the error names the step to list here, such as "pass:PlaceTypeTests". Apart from that, the option is for working on the compiler.

  • "pass:<name>": one optimization pass
  • "flow:<name>": one kind of result of the whole-program analysis
  • "flow-results": the whole-program analysis and all its results

  Takes a list of names, or one string with commas between the names. Bun.build throws if the compiler doesn't know a name.

  Equivalent CLI flag: --aot-disable

• 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
  • "missed-optimizations": calls that weren't inlined, loops that weren't optimized, and why
  • "allocations": where each object is allocated (stack, heap or removed), and why

  Equivalent CLI flag: --explain

• aotHeat?: AotHeat

  With aot: replace the compiler's estimate of how often each part of the program runs. The program behaves the same. The option is for working on the compiler.

  The compiler makes code that it expects to run often fast, and the rest small.

  • "everything-is-hot": all code runs often
  • "everything-is-cold": all code runs rarely
  • "only-loops-are-hot": every function is entered equally often, so only loops run often
  • "nothing-is-hottest": the estimate, without its list of the hottest functions
  • "shuffled": each function gets an estimate at random, the same one in every build

  Equivalent CLI flag: --aot-heat

• aotLogTypeMismatches?: boolean

  With aot: log every value that doesn't match its declared type.

  A mismatch never changes what the program does: the function falls back to its slow path and behaves as it does under bun run. Each log line has the location, the expected type and the kind of value it got, never the value itself. Lines go to stderr, or to the file in the BUN_AOT_TYPE_MISMATCH_LOG environment variable.

  Equivalent CLI flag: --aot-log-type-mismatches

• 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[]
• executablePath?: 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 implies 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.

  Equivalent CLI flag: --obfuscate

• outfile?: string
• target?: CompileTarget
• 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 }