Compatibility

An executable built with bun compile runs the same language and the same APIs as bun run. This page lists what differs.

A value that doesn't match its declared type isn't on the list. It falls back to the slow path, and the program behaves as it does under bun run.

If an error message sent you here:

What works the same#

• npm packages, with or without types, except for a few
• ES modules, CommonJS, require(), import() of a string literal, top-level await
• every node: and bun: module
• Workers and native addons
• eval and new Function, in the interpreter
• macros
• plugins of Bun.build, files, define, loader and the other build options
• proxies, getters and setters, generators, symbols, Reflect, private members, delete, BigInt, regular expressions

Some of these take a slow path: a Proxy used as an array, and an array with holes, with getters for elements or with inherited elements. They behave as under bun run.

What differs on purpose#

What isn't available#

Libraries that are known not to work#

These packages work under bun run and don't work in an executable. Each does something that bun compile rules out on purpose. The table says what that is, with the line of the package that does it, and links to the rule. The versions are the ones that were tried.

Most of them end in the same TypeError. It names the object and the property, and its stack trace points to the line in the package. Where the table cuts a TypeError short with ..., it ends like this one:

TypeError: Cannot assign to Function.prototype.call$0 because built-in objects are read-only in a compiled executable (bun compile differs from bun run here: https://bun.com/docs/compiler/compatibility)

The rows about built-in objects apply to bun run --aot and bun test --aot too, with the same messages. The row of async-listener and the rows about the loader and the module cache don't: there your program runs from its source files.

The lines of sass and asciidoctor belong to a language runtime, not to the package's own code. Other packages that are compiled from Dart with dart2js, or from Ruby with Opal, can stop at the same place.

Two old benchmarks add a method to Object.prototype. deltablue of Octane defines Object.prototype.inheritsFrom at the top level of its file, so the build fails with TS100014. string-tagcloud of SunSpider assigns Object.prototype.toJSONString and throws the TypeError when it starts.

These change built-in objects too, in ways that are allowed. They load, and change the same members as under bun run: core-js 3.51.0 (all of it, core-js/stable and core-js/actual), @babel/polyfill, babel-polyfill, react-app-polyfill, regenerator-runtime, es7-shim, reflect-metadata, symbol-observable, zen-observable, colors, date-utils, temporal-polyfill, mockdate, timekeeper, jest-date-mock, and the other packages of es-shims. So does sinon, fake timers included. A sinon.stub() of a read-only member, such as Array.prototype.push, throws like an assignment.

Type errors are TypeScript 7's#

The build reports the errors that tsc from TypeScript 7 reports, like bun check, whichever version of typescript your project has installed. A project that passes TypeScript 5 or 6 can still have errors. Coming from TypeScript 5 lists the options and defaults that changed.

TypeScript 7 also stopped reading five older patterns in JavaScript files. They still run. But when a TypeScript file imports one of your own .js files that uses them, with import type too, it no longer sees what TypeScript 6 saw, and the build stops at the TypeScript file.

The build doesn't report type errors inside a .js file, so only the TypeScript files that use it are affected.

Files without import or export#

For TypeScript, a .ts file that has no import and no export is a script, and everything at its top level is global. "moduleDetection": "force" turns that off. bun init writes it, and the build assumes it if there's no tsconfig.json.

Bun runs every file as a module, whatever moduleDetection says. So a variable, a function or a class of such a file exists only in that file. Its types follow tsc, and its values follow what runs:

A name that is both, like interface Point beside const Point, counts as code. To use it in another file, export it and import it there.

An interface Request or interface Node of your own in such a file adds to the one of the DOM types or of @types/bun, so tsc, bun check and the build all report what is missing from your objects. An export {} at the end of the file, or "moduleDetection": "force", makes the name the file's own.

Every script that your tsconfig.json includes counts, as for tsc, also one that the entry point never imports. Two scripts of one project that each declare interface Options share one Options.

Built-in objects are read-only#

The compiler turns array.push(x) into a few instructions without first checking whether somebody has replaced push. So nobody can. Replacing an existing member of a built-in object isn't supported. Adding a new one is fine, with the exceptions in the table.

function attempt(change: () => unknown): void {
  try {
    console.log(change());
  } catch (error) {
    console.log((error as Error).name);
  }
}

attempt(() => ((Array.prototype as any).last = 1));
attempt(() => ((Array.prototype as any).push = 1));
attempt(() => delete (String.prototype as any).slice);
attempt(() => Reflect.set(Array.prototype, "push", 1));
attempt(() => ((Object.prototype as any).extra = 1));
attempt(() => ((Date as any).tomorrow = 1));

bun compile ./builtins.ts && ./builtins

1
TypeError
TypeError
false
TypeError
1

A few members of the third and fourth groups can be replaced, because well-known packages do: String.prototype.at, trim, trimStart and trimEnd of strings, the HTML methods of strings such as bold and link, the methods of Set that take another set, such as union, Math.random, Math.sign, Math.sinh, Math.sumPrecise, JSON.parse, JSON.stringify, Date.now, Date.parse, Date.prototype.toString, toLocaleString, toLocaleDateString and toLocaleTimeString of dates, Number.parseFloat, Number.parseInt, Map.groupBy, Promise.try, RegExp.escape, Uint8Array.fromBase64, Uint8Array.fromHex and Buffer.poolSize. They follow the rule of the last group. toJSON can be added to Map.prototype and Set.prototype, and toLocaleString to a typed array constructor. The Reflect functions return false where an assignment would throw. Object.defineProperty() throws like an assignment. An assignment or a delete throws in sloppy-mode code too, which is what most CommonJS packages are. A package always finds out that it didn't replace the member.

In the last group, an assignment counts when the compiler can tell which object it goes to: console.log = f, const con = console; con[name] = f. If your code gets hold of console in a way that the compiler can't follow, such as out of a JSON.parse reviver, an assignment through that value to a member that nothing else assigns throws the same TypeError, with the member's name. Assign through the global name instead. delete and Object.defineProperty follow the same rule as an assignment.

The same goes for the global object as this. A constructor function that starts with if (!(this instanceof F)) return new F(...) can be called without new, and behind that test the compiler takes this for an instance of F. The global object passes the test only if you set F.prototype = Object.prototype. Then an assignment such as this[key] = value in that function goes to the global object in a way that the compiler didn't follow: it throws the same TypeError.

Object.freeze(), Object.seal() and Object.preventExtensions() work on all of these objects as they do under bun run, so a server can freeze Object.prototype when it starts, to guard against prototype pollution. So does an Object.defineProperty() that repeats what a member already is, or that only makes it read-only or non-configurable.

The build reports each such assignment that it can see as TS100014. It's an error if the assignment always runs, and a warning if it only might. The built-in objects of a node:vm context or a ShadowRealm that your program creates can be changed: each has its own.

A global that can't be replaced can't be shadowed either. A script that you run with vm.runInThisContext() or new vm.Script() shares its top-level let, const and class declarations with the whole program, so let Math = ... at the top of such a script throws a SyntaxError. Use another name, move the declaration into a function or a block, or run the script with vm.runInNewContext().

Bun and process#

An executable always runs on Bun, on the platform that you built it for. A test that asks which runtime this is has one answer, so the compiler answers it at build time. The code for the other runtimes isn't compiled, and what only that code imports isn't in the executable and doesn't have to be installed.

const isBun = typeof process !== "undefined" && "bun" in process.versions;

export function open(path: string) {
  if (isBun) return new (require("bun:sqlite").Database)(path);
  return new (require("better-sqlite3"))(path);
}

It makes no difference whether there is a ?. on the way, as in process?.versions?.bun. A const, or a let or var that is assigned once, keeps the answer for the functions that read it.

Only the globals count, and the process of import process from "node:process", which is the same object. A parameter, a variable or an import that is called Bun or process is read when the program runs, like any other.

So that the answers stay true, an executable can't replace what gives them. Assigning to, redefining or deleting the global process, or process.isBun, process.versions and process.release, throws the TypeError above. process.versions.bun, process.versions.node and process.release.name are read-only, so a program that overwrites process.versions.node to pass for another version of Node.js can't do that in an executable. The rest of the two objects works as it does under bun run: a loader can still add process.versions.pnp. The global Bun is read-only under bun run too. Every other property of process and Bun follows the rule of the last group.

New properties on built-in prototypes#

You can add a new property to the objects of the third group and to Error.prototype. It doesn't matter who adds it: your compiled code, code in a string or an --external package. Compiled code finds the property as it does under bun run. list.last finds an Array.prototype.last, and this.node = node in a class that extends Error runs a setter called node on Error.prototype.

The exceptions are the names that the language looks up by itself. A prototype of the third group that doesn't have such a name never gets it:

TypeError: Cannot assign to Array.prototype.next because built-in objects are read-only in a compiled executable (bun compile differs from bun run here: https://bun.com/docs/compiler/compatibility)

Put the method on your own object or class instead. A class that extends Array can have a then, a toJSON or a next.

Request, Response and five other classes#

The prototypes of Request, Response, Headers, Blob, URL and URLSearchParams are read-only too. So is the prototype of the request objects that Bun.serve passes to your routes handlers. File.prototype is the same object as Blob.prototype.

Use a subclass. It has a prototype of its own.

try {
  (Response.prototype as any).text = async () => "patched";
} catch (error) {
  console.log(String(error));
}

class Upper extends Response {
  override async text(): Promise<string> {
    return (await super.text()).toUpperCase();
  }
}

console.log(await new Upper("hello").text());

bun compile ./response.ts && ./response

TypeError: Cannot assign to Response.prototype.text because built-in objects are read-only in a compiled executable (bun compile differs from bun run here: https://bun.com/docs/compiler/compatibility)
HELLO

A subclass can override methods and getters such as text() and ok, add fields and call super.

These also work as usual:

• a property on one instance: Object.defineProperty(response, "url", { value })
• replacing a static function: URL.createObjectURL = stub
• replacing the global: globalThis.Response = Upper
• a polyfill that checks first: Headers.prototype.getSetCookie ??= ... assigns nothing, so nothing throws

Packages that change built-in objects#

A few packages change built-ins, mostly to support old browsers or to offer a shorter syntax in tests. Libraries that are known not to work lists the ones that stop, what you see, and what to use instead. It also lists well-known ones that load.

Code from strings#

eval, new Function and node:vm work, and so does a Worker made from a string. The build can't see their code, and the executable has no JIT, so Bun interprets it.

const add = new Function("a", "b", "return a + b");
const local = 5;
console.log(add(2, 3), eval("local * 2"), (0, eval)("typeof Bun"));

bun compile ./strings.ts && ./strings

5 10 object

That's fine for a template or a configuration file. It matters when a library generates its hot code that way: zod 4, ajv, fast-json-stringify and Elysia do. If the library has a mode without generated code, measure both: z.config({ jitless: true }), called before you create a schema, makes parse in zod 4 cheaper, while new Elysia({ aot: false }) makes a request slower. For Fastify, see below.

If your program never calls eval or new Function, the compiler assumes it has seen all the code that will ever run (a closed-world assumption, like GraalVM Native Image) and optimizes accordingly.

It finds these calls by tracking the functions as values, so const run = eval, Reflect.construct(Function, [code]), (() => {}).constructor(code) and new Proxy(Function, {})(code) all count.

A direct eval in strict code doesn't count if its string is known at build time and is only the name of a variable, as in eval("require"), or eval("quire".replace(/^/, "re")) in the @protobufjs/inquire package. It's compiled as a read of that variable.

Only a call counts. Naming eval or Function, storing one in an object or passing one to another function of your program costs nothing by itself. Neither does a call to a function that the compiler knows nothing about: it doesn't assume that such a call might be eval. The exception is a program that hands eval or Function to something that the compiler can't follow, such as the resolve function of Promise.withResolvers(), a proxy or the detail of an event. There it counts as called.

What it doesn't track is an eval or a Function that your program reads under a computed key, as in object[name](code) or globalThis[name](code). That holds for your own objects too. A table such as { "%eval%": eval, "%parse%": parse }, like the one in the get-intrinsic package, costs nothing however it's read, and table["%eval%"](code) counts as a call while table[name](code) doesn't. It doesn't track the third argument of Reflect.get(target, key, receiver) into the getter either, so this.constructor(code) in a getter that runs on a function that way doesn't count. In a program with no other such call, that one throws:

EvalError: Code generation from strings disallowed for this context: the compiler couldn't tell at build time that this call reaches eval() or the Function constructor. Call eval() or new Function() directly.

A few other ways to load code follow the same rule. They work where the compiler finds the call, and throw where it doesn't.

• Bun.plugin
• require and process.getBuiltinModule used as values, in a program where every import path is a constant

Code in a string can use any API, with one exception. Some of process, console and Bun is written in JavaScript, and the executable only contains the APIs that your program uses. If a string is the only thing that uses one of the others, that use throws:

const text = process.argv[2] ?? "process.stdout.write('hi\\n')";
try {
  new Function(text)();
} catch (error) {
  console.log(String(error));
}

Error: None of console._stderr, console._stdout, process.stderr or process.stdout was compiled into this executable because your code never uses them. To keep them, use one of them somewhere in your code. (bun compile differs from bun run here: https://bun.com/docs/compiler/compatibility)

The error is catchable. Using process.stdout anywhere in your own code fixes it.

This affects process.stdout, stderr, stdin, openStdin(), finalization, allowedNodeEnvironmentFlags and loadEnvFile(), console.Console and console.write(), and Bun.$, Bun.sql, Bun.SQL and Bun.peek().

A function of a node: module that your program imports and never calls isn't compiled either. A string rarely finds one, but it can: on an object such as process that inherits from EventEmitter, or by loading the module itself, as in process.getBuiltinModule("node:http").request(url) in a program that only has import { createServer } from "node:http". The call then throws '...' was not compiled into this executable because your code never calls it, with the function's name.

process.mainModule is undefined in a string unless a file of your program names it, as it is in every executable built without --aot. Besides import() of an entry point, it's the only path from a string to your modules, so without it the compiler knows every caller of what the other files export. require.cache is no such path: it lists none of them.

A string can import() an entry point of the build by its path. A JSON file or another data file that's compiled into the executable is different: a string finds it only if your program has a dynamic import() or require() of its own. Otherwise the import rejects with ERR_MODULE_NOT_FOUND, as in an executable built without --aot.

Everything that belongs to the language always works in a string: Array, Map, Promise, JSON, regular expressions, generators. So does everything that Bun implements natively, such as fetch, Bun.file and Bun.serve.

It's always the call that throws. Importing node:vm, node:worker_threads, node:repl or bun:ffi costs nothing and never fails. inspector.open() from node:inspector starts no debugger and doesn't throw, unless you build with --compile-inspector.

If your program needs none of it, --disallow-code-generation-from-strings turns it off in the executable, like the Node.js flag of the same name.

bun compile --disallow-code-generation-from-strings ./strings.ts && ./strings

EvalError: Code generation from strings disallowed for this context
      at /$bunfs/root/strings.ts:1:17

With the flag, a call to eval or new Function can only throw, so the compiler treats your program as if the call ran nothing. It knows every caller of your functions again, which means less code to compile and more that it can optimize, and --trim can remove the interpreter. A library that tries new Function inside a try, such as zod 4, falls back to plain code. A library that can't work without generated code, such as Elysia, throws the EvalError when it starts.

That fallback is faster here. zod 4 generates a parser for each object schema, and an executable has to interpret it. The plain code it falls back to is compiled. A POST route that checks an order with ten items (600 bytes of JSON) with zod, in requests per second on one core:

z.config({ jitless: true }) does the same for zod alone, without the flag.

With =strict, code from the disk fails with the flag's error too. require() and import() of a file that isn't in the executable throw EvalError: Code generation from strings disallowed for this context. --preload, -r, --require, --import and BUN_INSPECT_PRELOAD end the process with that error and exit code 1. An executable built without --aot does the same. Without the flag, you get the messages that say what to do.

Pass the flag when you build. BUN_OPTIONS can turn it on too, but that's too late for a string that's a constant. The compiler has compiled (0, eval)("1 + 1") and new Function("return 2") like the rest of your program, so they still run. A string that's put together at run time throws.

Fastify#

Fastify generates code from strings in three places:

• The router. find-my-way generates a few short functions for each route when the server starts, and a request calls two or three of them. That's 2 to 7% of a request. You can't turn it off.
• Response schemas. fast-json-stringify generates a serializer for each schema.response.
• Request schemas. ajv generates a validator for each schema.body, schema.querystring, schema.params and schema.headers.

The serializers and validators run on every request, and interpreting them can cost more than the rest of the request. A route that returns 3.5 KB of JSON runs six times as many instructions with a response schema as without one. You can keep the schemas and avoid both.

Serialize with JSON.stringify.

const app = Fastify();
app.setSerializerCompiler(() => JSON.stringify);

In Bun, JSON.stringify is faster than the generated serializer even with the JIT. The compiled server answers that route more than twice as often per second. There's one difference: fast-json-stringify leaves out properties that aren't in the schema, and JSON.stringify writes every property of the object you return.

Write the validators to files before you compile. @fastify/ajv-compiler can give you the source code of a validator instead of calling new Function. Save it to a file, and Bun compiles it with the rest of your program.

import { StandaloneValidator } from "@fastify/ajv-compiler";
import Fastify from "fastify";
import { writeFileSync } from "node:fs";

const writes = process.argv[2] === "write";
const buildValidator = writes
  ? StandaloneValidator({
      readMode: false,
      storeFunction: (route, code) => writeFileSync("./order-validator.js", code),
    })
  : StandaloneValidator({
      readMode: true,
      restoreFunction: route => require("./order-validator.js"),
    });

const app = Fastify({ schemaController: { compilersFactory: { buildValidator } } });

app.post("/orders", { schema: { body: orderSchema } }, placeOrder);

await app.ready();
if (writes) process.exit(0);
await app.listen({ port: 3000 });

bun add @fastify/ajv-compiler ajv
bun ./server.ts write
bun compile ./server.ts

route has the method, the url and the httpPart ("body", "querystring", ...) that the validator is for. If you have more than one schema, name each file after them. Give each require() a constant path, because a module behind a computed path isn't compiled. The validators import helpers from ajv, so it has to be installed.

With both changes, a route that validates an order of ten items answers about 1.6 times as many requests per second, the same as without schemas.

WebAssembly#

A .wasm file that your program imports is compiled at build time.

import path from "./add.wasm";

const bytes = await Bun.file(path).arrayBuffer();
const { instance } = await WebAssembly.instantiate(bytes);

The executable recognizes the module by its bytes. So it makes no difference how your program reads the file, or which function of WebAssembly it passes the bytes to.

Bun interprets every other module: bytes that your program downloads, decodes from a string or assembles itself. The executable has no JIT, so a tight loop runs about 20 times slower there.

On some machines, and with some memories, the executable can't use the compiled code of a module. The run-time log says so.

Dynamic imports#

bun compile compiles every module that the entry point reaches through an import or require. When an import path isn't a constant, the compiler uses the parts of it that are.

const wanted = process.argv[2] ?? "csv";
const plugin = await import("./plugins/" + wanted + ".ts");
console.log(plugin.name);

export const name: string = "csv";

export const name: string = "json";

Every path here starts with ./plugins/ and ends with .ts, so the compiler includes every such file below plugins/. The executable contains both plugins and runs without your source files.

bun compile ./app.ts --outfile elsewhere/app && cd elsewhere && ./app json

json

The require doesn't have to be called under its own name. The compiler follows it into a variable that's never assigned again, and into a parameter of a function that's called where it's written. That covers the wrapper that TypeScript writes for "module": "umd", which an executable built without --aot doesn't follow.

(function (factory) {
  if (typeof module === "object" && typeof module.exports === "object") factory(require, exports);
  else if (typeof define === "function" && define.amd) define(["require", "exports", "./part"], factory);
})(function (require, exports) {
  exports.part = require("./part");
});

A path that's one of a few, like require(fast ? "./fast.ts" : "./small.ts"), adds those files and no others. Native addons lists the forms that the compiler follows.

A path with no constant start, like require(name), adds nothing to the executable. Of your own files it finds the entry points, by the path the file had at build time, as in an executable built without --aot. A file that's only in the executable because another file imports it isn't found, even after it has run.

error: Cannot load '/$bunfs/root/inside.ts': this executable can't load a module from a dynamic path. Pass the file to bun compile as another entry point.

To load a file by a dynamic path, pass it as an additional entry point. An entry point can be a glob pattern.

bun compile ./app.ts './extra/*.ts' --outfile app

A package that's loaded by a dynamic name, like the database driver of an ORM, works the same way. Pass the file that the package's main or exports points to. require(name) and import(name) then find it by the name of the package, from every file that sees the package in its node_modules, and the executable doesn't need node_modules on disk.

bun compile ./app.ts ./node_modules/pg/lib/index.js --outfile app

A package with exports is found by the names it exports, patterns like "./features/*" included. A package without exports is also found by the paths of its files, like pg/lib/client.

Paths that start at the file's folder#

The compiler knows that __dirname, import.meta.dir and import.meta.dirname name the folder of the file, and it follows path.join and path.resolve when their first argument is one of them. require(path.join(__dirname, "..", "package.json")) is compiled like require("../package.json").

Two things turn such a path into a dynamic path:

• The file changes __dirname, __filename or import.meta. That includes handing import.meta to a function. Files that only read them aren't affected.
• The program replaces path.join or path.resolve. The executable compares the path that the call returned with the path that Bun's own function returns. If they differ, require throws and import() rejects. bun run would load whatever file the replacement named.

error: Cannot load './plugin.js': path.join or path.resolve was replaced and returned a different path. This executable can't load a module from a dynamic path.

Built-in modules#

The same rule applies to node: and bun: modules. The executable contains the ones that your program, a package or another built-in module imports by a constant name.

A name doesn't have to stand in the call. If your program or a package loads a module by a name that the compiler can't work out, or hands require, module, process or import.meta to code that the compiler can't follow, the executable also contains every built-in module whose name is written as a string anywhere in the program, with or without node:.

A string doesn't count if it's only compared (name === "fs", case "fs":), used as a property key (table["fs"]), or kept in an array or a Set that the program only searches (names.includes(name), names.has(name)). No string counts in a program where every import has a constant name. A dynamic path that can't be the name of a built-in module, like require("./locales/" + name), doesn't make strings count either.

If a function passes its parameter to require(), import() or process.getBuiltinModule() and the program only ever calls that function directly, as with tryRequire above, the compiler takes the names from the calls. Such a function doesn't make other strings count. A require(name) doesn't add the rest, so one such call in a package doesn't put node:repl and node:dgram into your server. A name that comes from outside of the program, or that's put together from parts, only finds a module that's in the executable for another reason.

import "node:path";

const name = process.argv[2] ?? "node:path";
console.log(Object.keys(require(name)).length > 0);

bun compile ./load.ts && ./load node:path && ./load node:dgram

true
error: Cannot load 'node:dgram': it isn't in this executable. Import it by name somewhere in your program to keep it. (bun compile differs from bun run here: https://bun.com/docs/compiler/compatibility)

A built-in module that a dynamic name finds works like one that you import, even if it's only in the executable because another built-in module imports it.

To keep a built-in module whose name isn't written anywhere in your program, import it once by its name. The import costs nothing until the module is used.

import "node:dgram";

The same goes for node:cluster. server.listen() in a cluster worker asks the primary for its socket, and that code is in the executable only if your program imports node:cluster, itself or through a package. A program that forks itself does. If another program starts your executable as a worker, with cluster.setupPrimary({ exec }), and your program never imports node:cluster, listen() fails with Cannot load 'node:cluster': it isn't in this executable instead of listening on its own. import "node:cluster" fixes it.

Some properties of process, Bun and console are written in JavaScript too: process.stdout needs node:tty, and Bun.sql needs bun:sql. The executable contains the ones your program can reach. Reading process[name] with a dynamic name, or storing process where the compiler can't follow it, keeps all of them.

The compiler follows a built-in module through variables, parameters, return values and properties of objects that your own code creates, so fs[name]() with a dynamic name keeps every function of node:fs wherever fs got there that way. It can't follow a module through an object that came from outside your code: after const box = event.detail; box.url = require("node:url"), box.url[name]() throws '...' was not compiled into this executable because your code never calls it, unless your program also calls that function by name or reads url[name] somewhere the compiler can follow. The same goes for a method of a class of a built-in module: after box.handle = await open(path), box.handle.readLines() works, and box.handle[name]() throws that error unless your program also calls readLines() by name or reads handle[name] on a handle the compiler can follow.

The code behind the IPC channel is kept for process.on("message", ...) only when the compiler can see that the call is on process: called on process itself, or on a variable or parameter that holds it. If process got there through a value the compiler can't follow, like error.cause, a message that carries a Buffer or a handle throws an error that names what's missing. Using process.send anywhere in your code keeps it.

Code that isn't in the executable#

A dynamic import() or require() can only load code that's in the executable. Anything else throws: JavaScript, TypeScript, WebAssembly or a native addon. So does everything that Bun would read as JavaScript or turn into it: a file with no extension, a file with an extension that Bun doesn't know, a Markdown file, and a data: or blob: URL.

error: Cannot load '/home/me/plugins/late.ts': it isn't in this executable, which only runs code that was compiled into it. Pass the file to bun compile as another entry point, or build with --aot-allow-code-from-disk.

The error has the code MODULE_NOT_FOUND from require() and ERR_MODULE_NOT_FOUND from import(), like a file that doesn't exist. The build warns at each import where this can happen.

warn: TS100064: this import path isn't a constant. If it resolves to code that isn't in the executable, the import throws at run time (data files still load). Add the file as an entry point, or build with --aot-allow-code-from-disk

An --external package has require, module, require.cache and every built-in module, whole: the compiler can't see what the package calls, so a build with --external compiles every function of the built-in modules in the executable, not only the ones that your program calls. That makes the executable a few megabytes larger. The package doesn't see the modules of your program, as in an executable built without --aot: its module.parent has the path of the file that required it and empty exports, and require.cache lists the files that were loaded from disk. If a file of your program names a way between module objects, the package finds your modules through process.mainModule too. Built-in objects are read-only for it too: it can add a global or a property, and it can't replace one that your compiled code uses. globalThis.fetch = polyfill in such a package throws a TypeError if your program calls fetch.

createRequire(), import.meta.require() and module.require() follow the same rules. The compiler follows createRequire from node:module to the files that its require names, so a program can't replace createRequire.

new Bun.Transpiler() works and costs nothing: it turns text into text. A macro in that text is code that the build never saw, so it follows the rule for code from strings. Making a transpiler doesn't count as a call to eval, and in a program with no such call, transform(), transformSync() and scan() throw for a text that calls a macro:

error: Macros cannot be used in this executable, which only runs code that was compiled into it

Load code from disk#

A plugin, a config file, a tool that your user wrote: the build never sees them, because their paths are only known when the program runs. With --aot-allow-code-from-disk, a dynamic import() or require() loads such a file from disk, as in an executable built without --aot. It isn't compiled. Bun transpiles it and interprets it, without a JIT, like code from a string.

const plugin = await import(Bun.pathToFileURL(process.argv[2]).href);
console.log(plugin.default(20));

import { cpus } from "node:os";

export default (n: number) => n * 2 + Math.sign(cpus().length);

bun compile --aot-allow-code-from-disk ./host.ts && ./host ./plugin.ts

41

• Every kind of file loads that loads in an executable built without --aot: JavaScript, TypeScript, JSX, JSON and the other data files, WebAssembly, a native addon, a data: or blob: URL. The path can be absolute, relative to the working directory, or a file: URL.
• The file imports what it likes: files beside it, packages in a node_modules on disk, and every node: and bun: module. It gets the same node:fs and the same EventEmitter as your program. A built-in module that isn't in the executable is interpreted too. A package.json on disk is only read if you build with --compile-autoload-package-json, as in any executable.
• The two sides are one program. The file calls your compiled functions and they call its functions. Objects, classes, promises and exceptions cross in both directions. A type of yours says nothing about what such a file returns or stores, and nothing throws because of that.
• Bun.plugin applies to it. onResolve, onLoad and module() run for what the file imports, so a host can hand its own modules to a plugin: build.module("my-sdk", () => ({ exports: sdk, loader: "object" })).
• It doesn't get the files of your program by path. An entry point is found, and it's the compiled module, which runs once. Any other file of the executable isn't, as described above.
• Built-in objects are read-only for it too.

The option has a price, and only a program that can reach such an import pays it:

• The executable is larger. It keeps Bun's transpiler and the source code of Bun's built-in modules. It also holds every function of the built-in modules that are compiled into it, not only the ones that your program calls. That's a few megabytes, and --trim can't remove the transpiler or the interpreter.
• The program can run slower. The compiler can't see what the file does with what it's handed, so it proves less about the objects and functions that the file can get hold of. Those include everything that the built-in modules export. A server on node:http can need up to a third more CPU time for a request.

A program without a dynamic import() or require() is the same executable with and without the option.

With the option, a name that comes from outside of the program finds every built-in module. One that isn't in the executable isn't compiled: Bun interprets it, like a file from disk.

process.getBuiltinModule(name) is the exception. It never loads a file, so it doesn't make the executable ready for code that wasn't compiled. In a program that has no other dynamic import, it only finds a module that's in the executable, with the option too.

error: Cannot load 'node:dgram': it isn't in this executable. Import it by name somewhere in your program to keep it. (bun compile differs from bun run here: https://bun.com/docs/compiler/compatibility)

In Bun.build, the option is compile: { allowCodeFromDisk: true }.

The compiler also follows require under another name, as long as it can see that the name holds require. Where it can't, every path is a dynamic path, a string literal too.

A function that's called where it's written and returns require counts as another name too. That's the __require helper that esbuild puts into ES module bundles.

With code splitting, esbuild and bun build export the helper from a shared chunk. The compiler follows require, import.meta.require and createRequire() from an export to an import for built-in modules, whose names mean the same in every file. Any other path is still a dynamic path there.

process.getBuiltinModule("node:fs") with a string literal is compiled like require("node:fs"), also on a variable that holds process or globalThis and is never assigned again. If your program assigns a function of its own to process.getBuiltinModule, as require-in-the-middle does, every call runs that function. The compiler still follows process.getBuiltinModule("node:module").createRequire(import.meta.url) to the files that its require names, so the executable compares the createRequire that it's about to call with Bun's own. If the replacement returned an object with a different one, the call throws Cannot call createRequire: process.getBuiltinModule was replaced and returned a different createRequire. Under another name, or on a process that came through a parameter or a property, the function loads the built-in modules that your program names. It can't see the function behind a computed key (process[key](name)): such a call throws Cannot load '...': this executable can't load a module from a dynamic path.

require() can't wait. If it reaches an ES module outside of the executable that has a top-level await, it throws a TypeError that tells you to use await import().

Frameworks that load your pages by path#

Next.js and Angular load your application's pages and routes from paths that they build while the server runs, so the compiler doesn't find them. Pass the pages as additional entry points, and they are compiled. Pass the rest of the build output with --asset, and the server reads it out of the executable.

# Next.js with `output: "standalone"`, in .next/standalone
bun compile ./server.js ".next/server/**/*.js" --asset .next --asset public --asset node_modules/@img --outfile server

The result is one file that needs nothing else on the machine that runs it. Bun expands the quoted pattern itself. node_modules/@img holds sharp, which resizes the images of next/image; without it Next.js serves them at their original size. Next.js can't write its page cache into the executable, so it keeps the cache in memory. It can't store the images it has resized either, and logs Failed to write image to cache for each of them.

--compile-in-place builds an executable that only runs on the machine that built it: modules keep their paths on disk, and whatever wasn't compiled or embedded is read from there.

bun compile --compile-in-place ./server.js $(find .next/server -name '*.js') --outfile server

For Angular the files are $(find dist/site/server -name '*.mjs' -not -name server.mjs). Nuxt, SvelteKit, Astro and React Router need no additional entry points. Pass what the server reads from disk with --asset:

bun compile ./.output/server/index.mjs --asset .output/public --outfile server # Nuxt
bun compile ./dist/server/entry.mjs --asset dist/client --outfile server # Astro
bun compile ./build/index.js --asset build/client --asset build/prerendered --outfile server # SvelteKit
bun compile ./server.ts --asset build/client --outfile server # React Router, with a server of your own

Without the entry points, the first request fails with the error above.

Options that load code#

--preload and a few other options load code that the compiler never saw. What the compiler proved about your program only holds while nothing else runs, so an executable rejects them. The exception is an executable that's built with --aot-allow-code-from-disk and whose program has a dynamic import() or require(): it's ready for such code, so it takes --preload, -r and --import.

console.log("hello");

console.log("before");

bun compile ./greeting.ts && BUN_OPTIONS="--preload ./before.ts" ./greeting

error: --preload can't be used with this executable because it only runs code that was compiled into it. Rebuild it with --compile-inspector to load other code

The executable exits with code 1, before any of your code runs. To run before.ts first, import it at the top of greeting.ts.

An executable reads the bunfig.toml of the directory it's started in. That file may be there for bun run, so what it would load is ignored and isn't an error. The build has bundled your pages, so no server needs the plugins.

A module of Bun's own library carries out the --trace options of the third row, and an executable has only the modules that your program uses. They print or write something for you to look at, and your program does the same without them. So the executable prints one line for each and runs your program. --stack-trace-limit works like in bun run.

warn: --trace-exit is ignored by this executable because it only runs code that was compiled into it. Rebuild it with --compile-inspector to load other code

In --compile-exec-argv, the options of the first and the third row fail the build.

Three build flags change that.

• --compile-inspector has a price. A debugger can run any code in any scope, so the compiler can prove less about the program. The executable is larger and slower, and --trim removes no features.
• An option in --compile-exec-argv is part of the build. --inspect there needs no --compile-inspector.
• Editors set BUN_INSPECT_CONNECT_TO for every process that you start from their terminals. An executable built without --compile-inspector ignores it and runs.

The module cache#

A module of the executable runs at most once. require.cache and Module._cache don't list it, and delete require.cache[path] does nothing to it. That goes for CommonJS modules, ES modules and JSON files. An executable built without --aot does the same.

globalThis.runs = (globalThis.runs ?? 0) + 1;
exports.runs = globalThis.runs;

const path = require.resolve("./counter.cjs");
console.log(require("./counter.cjs").runs, path in require.cache);
delete require.cache[path];
console.log(require("./counter.cjs").runs);

bun run ./again.cjs && bun compile ./again.cjs && ./again

1 true
2
1 false
1

Circular requires work as under bun run. A module that is required again while it's still running doesn't start over. The second require() returns its module.exports as it is at that moment, with the names that have been assigned so far. The rest show up as the module keeps running.

One case differs. A callback that you handed to other code may call require() on an ES module while that module is still running, without any import or require() leading from the module back to the file of the callback. The call then returns the module's namespace object, and reading an export that isn't initialized yet throws a ReferenceError. Under bun run that's what happens if an import started the module; if a require() started it, the call returns an empty object.

A CommonJS module that throws isn't tried again. The require() that started it throws. Every later require() of that module throws the same error, as it does for an ES module. Under bun run the CommonJS module would run again, so a program that repeats a require() until something outside of it has changed keeps getting the first error.

In one case nobody gets the error, under bun run and in an executable alike. The CommonJS module is the entry point or was started by an import, it calls require() on an ES module that imports it back, and then it throws. The ES module has already taken the names that were exported by then, so the import counts as done. Every later require() of the CommonJS module returns the namespace object of that import: its default is the module's module.exports, next to the names it had at that moment.

A file that your program loads from disk at run time isn't part of the executable: an --external package, or a config file that a package reads with require(). It's in require.cache, delete takes it out, and it runs again at the next require(), as under bun run.

A module of the executable can't be loaded a second time in another form. new Bun.ModuleGraph().import(url) of one rejects with ERR_MODULE_NOT_FOUND: a second graph would have to run the module again from its file. require(path, { type: "text" }) with a path that is put together at run time throws as well, because the file isn't there to be read. Use import(path, { with: { type: "text" } }) with a constant path: the text is then included at build time.

error: Cannot load '/$bunfs/root/app.ts': it's compiled into this executable, and a compiled module can't be loaded a second time (for example into a Bun.ModuleGraph).

Loader hooks#

The compiler resolves every import and every require() of a constant path at build time, and compiles it to a call of the module. Nothing in node:module is asked on the way, so a hook doesn't see those.

Frameworks such as Next.js install the first two when they are loaded, to point a few names at their own copies of a package. In an executable the names that are constants already point where the build found them.

A loader for an extension that no file in the executable has is stored as under bun run. Packages such as handlebars register one for their own kind of file (require.extensions[".hbs"]) when they are required, and it changes nothing that was compiled.

Cannot replace a loader in Module._extensions: imports in this executable were resolved at build time, so the module loader can't be patched.

Packages that patch the loader to transpile, trace or mock what a program requires don't see the modules of an executable. Run such a program with bun run, or build it with --no-aot.

Module objects#

module, require.main and process.mainModule work as under bun run, and so do children and parent of the objects they give you.

console.log(require.main === module, module.parent?.filename);
for (const child of module.children) console.log(child.id, Object.keys(child.exports));

require.main, process.mainModule, module.children and module.parent are the only ways from the object of one module to the object of another. The compiler looks for them in the text of your program: module.children, const m = module; m.parent, show(require.main). What it can answer at build time doesn't count: require.main === module, require.main.filename, and !module.parent in most files.

• If any file names one of the four, all four work everywhere, also in a string that you eval and in an --external package. It doesn't matter whether the code that names it ever runs.
• If no file does, all four are undefined for everybody, as in an executable built without --aot. That only shows where your code gets to them in a roundabout way: module[key] with a computed key, or a module that came out of an array or back from native code. The rest of such an object works: module.exports, module.id, module.filename, require.resolve(), and require(path), which finds the entry points.

On an object that the compiler didn't expect anybody to reach, children is undefined if it would have to list a module for which the compiler keeps no exports object, and parent likewise.

import.meta.require, require in an ES module and a function that createRequire() makes for the file that calls it count as the require of that file. A file that they load has the module object of the calling file as its parent for as long as the program runs, and a CommonJS file lists it in its own module.children. Under bun run each of these functions has a module object of its own: that object is the parent and lists the children, and once nothing else holds it, it is collected and parent reads undefined.

If the four always worked, one require that a package stores in a table would make the compiler keep an exports object for every CommonJS module of your program. Most need none.

Re-exports of CommonJS modules#

The names that a CommonJS module exports are only known once it has run. The same goes for a JSON file, a built-in module and a module outside of the executable. When an ES module re-exports one of these with export *, one rare case differs from bun run. It is about the namespace object that import * as ns gives you. Named imports work the same.

A file has export * for two ES modules that both export x. That makes x ambiguous, so the namespace object of the file has no x. If a third export * of that file re-exports a CommonJS module that exports x as well, the compiled namespace object has the CommonJS value.

Workers#

The compiler finds the file of a worker whose path your code writes out, and compiles it, with everything it imports, as one more entry point. Any other worker you pass as an additional entry point, like in any executable.

A Worker has its own global object, so the compiler treats each entry point as a separate program when your code starts Workers. What a worker does to a class, a prototype or a shared module doesn't slow down the main thread's code, and the other way around. A module that both import is compiled once for each, so when your entry points share most of their code, they are compiled as one program.

declare var self: Worker;
self.onmessage = event => self.postMessage(event.data * 2);

const worker = new Worker("./worker.ts");
worker.onmessage = event => {
  console.log(event.data);
  worker.terminate();
};
worker.postMessage(21);

bun compile ./spawn.ts --outfile spawn && rm worker.ts && ./spawn

42

These all name a file that the compiler finds:

The path can pass through const variables, parameters of functions in the same file and exports on its way to new Worker(), of the global Worker or of node:worker_threads.

bun run looks for a relative path like "./worker.ts" from the working directory. An executable looks in itself first, from the folder of its entry point, or from the folder that all of them share. So does the compiler.

A name without ./ in front, like "some-package/worker.js" or "worker.ts", leads to a package, else to a file, like under bun run, and from that same folder. A file above that folder is found too, like new URL("../workers/job.ts", import.meta.url) in src/main.ts. Only a path that new URL() or path.join() leads two or more folders above it isn't, because nothing is left of the executable's own folder in such a path: write "../../workers/job.ts", or pass the file as an additional entry point. The compiler only follows the paths in your own files: a worker that a package in node_modules starts from one of its files isn't compiled, because most programs that import such a package never start it. A package of your workspace that is only linked into node_modules counts as your own files. Pass such a file as an additional entry point. A path that names no file changes nothing about the build, and the Worker fails to load.

You don't have to list a worker that you embed with the file loader and start by the path of the copy. The compiler follows the import to new Worker() and compiles the file, with everything it imports, as one more entry point:

import path from "./worker.ts" with { type: "file" };

const worker = new Worker(path);

The path doesn't have to go straight from the import to new Worker(). It can pass through variables, objects, arrays, functions and promises.

A file that you embed for another use, like a script that a server sends to browsers, stays a file. The compiler goes by what your program does with the path. A path that only ever reaches new Worker() is a worker. If the same path can also reach something like Bun.file() or fs.readFile(), it could be either. The compiler tries up to four files like that, and none of them if there are more. A Worker that gets the path of a file that wasn't compiled fails to load, so the build warns where that can happen:

warn: TS100071: This Worker may start from an embedded file that isn't compiled, and then it fails to load: "/home/me/app/site/index.js", "/home/me/app/site/login.js", "/home/me/app/site/settings.js" and 97 more. Add the file as an entry point, or pass its import straight to new Worker()

You don't have to list a worker that starts from a data: URL either, if the whole URL is known at build time. The compiler decodes it and compiles what it holds as one more entry point:

const code = `postMessage("from the worker")`;
const worker = new Worker("data:text/javascript," + encodeURIComponent(code));

The URL can be a string, a template or a + of constants, with encodeURIComponent() or btoa() around a part of it, percent-encoded or in base64, and wrapped in new URL(), which node:worker_threads asks for. It can pass through const variables, parameters of functions in the same file and exports on its way to new Worker(). The code is read as TypeScript with JSX whatever type the URL names, like under bun run, and its imports are resolved from the directory you build in. A dynamic import() in a data: URL only finds a built-in module or an absolute path, like under bun run and in Node.js.

The same goes for the code that you pass to new Worker(code, { eval: true }) of node:worker_threads, and for an object URL, if the code and the type of the Blob are known at build time:

const code = `postMessage("from the worker")`;
const worker = new Worker(URL.createObjectURL(new Blob([code], { type: "text/javascript" })));

The options and the parts of the Blob have to be written as literals, { eval: true } and [code]. The Blob and the URL can be kept in const variables. The executable knows the code by what it says, so a Blob that your program makes elsewhere with the same text and the same type starts the compiled code too. In such a Worker import.meta.url, Bun.main and stack traces show a blob: URL that is the same in every run.

If the code in the URL, or in a file that the compiler found by its path, has a syntax error or an import that can't be resolved, the build leaves it out. It prints what's wrong as warnings, and the Worker fails as it does under bun run:

warn: TS100072: The code that this Worker starts from can't be compiled, so the Worker fails to load

Any other error in that code stops the build, as it does in an entry point that you list: a type error in worker.ts is the same error as in main.ts.

A Worker that you create from a data: URL, an object URL or eval code that your program puts together at run time works too. Its code is code from a string, so Bun interprets it, and the built-in modules it imports too. It shares nothing with your compiled code: it can use any API, built-in objects aren't read-only in it, and it makes the rest of your program neither larger nor slower.

With --trim such a Worker fails to load, like a Worker from a file on disk. So it does with --disallow-code-generation-from-strings=strict, where new Worker() throws the flag's EvalError.

A Worker that you create from a path that your program puts together at run time runs code that isn't in the executable, so it fails to load: the Worker gets an error event. Pass the file as an entry point. With --aot-allow-code-from-disk it loads, in a program that also has a dynamic import() or require().

A file can start itself as a Worker. To tell the two threads apart, use Bun.isMainThread, not import.meta.main. In an executable with a single entry point, import.meta.main is decided at build time, like in any executable: it's true in that file on every thread. Under bun run it's false in the Worker. With more than one entry point it's false in a Worker here too.

Everything is one program when entry points can meet in one global object: when your code calls import() or require() with a dynamic path, which finds any of them, or passes preload to new Worker(). The program of that global object has to include all of them, so separate programs would only repeat it.

Native addons#

require("./addon.node") embeds the addon in the executable, like in any executable. process.dlopen(module, path) loads one from disk, and its path can be computed. Calls into either work the same. A require() with a computed path doesn't load an addon, because it only finds code that's in the executable.

A package usually ships one addon per platform and makes the name of the file out of process.platform and process.arch. The compiler knows both, so such a name is a constant to it, and the executable contains the one addon that it loads.

module.exports = require(`./my-app.${process.platform}-${process.arch}.node`);

The same goes for "./my-app." + process.platform + ".node", for path.join(__dirname, name), for a require from createRequire(), and for the loaders that NAPI-RS generates: a switch or a chain of ifs over the platform and the architecture, where each arm requires the file beside the loader or else the package for that platform, like @my/app-linux-x64-gnu. Such a loader first asks existsSync(join(__dirname, "my-app.linux-x64-gnu.node")). An embedded addon keeps its name, so the answer is true. In an executable built without --aot the name gets a hash, my-app.linux-x64-gnu-2ecze33x.node, which is also what Bun.embeddedFiles lists there.

Where only the start of a package's name is a constant, as in require(`my-app-${parts.join("-")}`), the executable contains every installed package whose name starts with my-app-.

A name can also be one of a few. The compiler follows each of them, and the executable contains every one that's installed:

• an entry of a table, as in names[process.platform][process.arch]
• an element of a list that a loop tries, as in for (const path of paths) require(path), or that forEach, map, filter or find hands to a function written in the call
• a value or a key of a table, as in for (const name of Object.values(names))
• what a function in the same file returns, and what's passed for a parameter of a function that's only ever called
• a variable that's assigned in more than one place, or added to outside of a loop, as in name += "-musl"
• a list that's joined, as in parts.join("-"), with what parts.push() adds outside of a loop
• what require.resolve() or import.meta.resolve() returns for any such name or for a constant, handed on as it is, as in require(require.resolve(name))

The table or the list has to be written in the file and stay as it's written: the file only reads it, and doesn't export it or pass it to a function. In such a name the compiler also takes const { platform, arch } = process, what require("node:process") returns, os.platform() and os.arch() for the platform and the architecture that the executable is built for.

The compiler still warns that such a path isn't a constant. If it can't follow a name, pass the addon as another entry point, and the loader finds it by the name that it makes.

bun compile ./app.ts ./node_modules/my-app-linux-x64-gnu/my-app.linux-x64-gnu.node --outfile app

An addon is native code. It can keep, call and change whatever your program hands it, right away or later, and it can read, call and change globals by name. Built-in objects are read-only for it too. napi_run_script runs code from a string, so it throws the same EvalError as eval unless the compiler found a call to eval or Function in your program.

On Linux, compiled code raises SIGSEGV and SIGBUS itself and handles them before anything else does. An addon or a library can still set a handler for either one with sigaction() or signal(). The handler is called for every other SIGSEGV and SIGBUS, the same as without --aot. Blocking them with pthread_sigmask() or sigprocmask() does nothing. All of this works on calls to the C library's functions by name. A library that makes the rt_sigaction system call itself, or that gets the function from dlsym() with RTLD_NEXT or a handle to the C library, takes the executable's place. It has to call the handler that was there before for any signal it didn't raise.

Plugins and build options#

Plugins of Bun.build work with compile: { aot: true }. The compiler is handed what your plugins resolve and load, never what's on disk. Which names a CommonJS file exports and in which order modules run come from the text that onLoad returns.

await Bun.build({
  entrypoints: ["./app.ts"],
  compile: { outfile: "./app", aot: true },
  plugins: [
    {
      name: "settings",
      setup(build) {
        build.onResolve({ filter: /^settings:/ }, args => ({ path: args.path.slice(9), namespace: "settings" }));
        build.onLoad({ filter: /.*/, namespace: "settings" }, async args => ({
          contents: `export default ${JSON.stringify(await readSettings(args.path))};`,
          loader: "js",
        }));
      },
    },
  ],
});

All of this behaves as in a build without aot, and each hook gets the same arguments:

• onStart, onResolve, onLoad, onEnd, defer(), and onBeforeParse with a native plugin
• several plugins, which are asked in order until one answers
• filters, namespaces, modules that are in no file, and what such a module imports
• external: true
• every loader, contents as a string or as bytes, and answers that come late
• a plugin that throws or rejects: the build fails with its message
• answers for the entry point, for a package in node_modules, for a CommonJS file, for a file of a page
• files, macros, define, loader, env, conditions, external, packages, drop, features, jsx, tsconfig, root, minify and sourcemap
• which file of a package ends up in the executable: "exports" and conditions first, then "module" for an import and "main" for a require(). If anything requires the package, its imports use "main" too, so there's one copy. bun run always takes "main"
• which loader a file gets: with { type: "file" } and the loader option come before the extension, and a file with an extension that Bun doesn't know is embedded as it is, for import and for require()

This differs:

The text that onLoad returns is type checked like a file, and its types are what the files that import it see.

Plugins for Solid, Vue or Svelte return JavaScript (loader: "js" or "jsx") for a TypeScript file, so the types are gone from what they return. In that case the JavaScript is compiled, and the files that import it get their types from the file on disk, like in your editor. The build doesn't report type errors inside of that file. Your editor and bun check do. import type { Props } from "./view.tsx" keeps working.

onResolve doesn't change what the type checker reads: it resolves an import as TypeScript does. So a module that's in no file needs a declaration, like in your editor.

declare module "settings:*" {
  const settings: { port: number };
  export default settings;
}

If a module doesn't match its declaration, or the JavaScript from a plugin doesn't match the file it was made from, the program behaves as under bun run.

Metafile#

--metafile, --metafile-md and metafile in Bun.build write the same format as without --aot. inputs lists every file of yours and of your packages that's in the executable, with its imports. Nothing is bundled, so a few things differ:

• outputs has one entry, the executable, whatever the number of entry points. Its entryPoint is the first one.
• bytes of the output is the size of your compiled program inside of the executable. That includes the parts of Bun's own modules, like node:fs, that are compiled with it. It doesn't include the Bun runtime.
• bytesInOutput is the machine code of the functions in that file. A function that's inlined counts for the file that calls it.
• Files that a computed path or import.meta.resolve names are inputs, and imports of the file that names them.
• An import that's only types, or that nothing uses, isn't listed. When a file that only re-exports is left out of the executable, its importer lists the files behind it instead, without original.

The executable is the same with and without a metafile.

bun build on the command line has no plugins, with or without --aot. Bun.plugin in your program is about code that isn't in the executable. As in every executable from bun build --compile, a plugin is never asked for a module that's in the executable, whatever its filters match.

Function.prototype.toString()#

The executable includes the source code of your functions, with the types removed, and toString() returns it. It's the text of your file. bun run returns what its transpiler printed, so line breaks, indentation and quotes can differ.

TypeScript's parameter properties go with the types. The text of class Point { constructor(public id: number) {} } is class Point { constructor(id) {} }, where bun run shows the field and the assignment that it compiles the property to, id; and this.id = id;. new Point(1).id is 1 in both. A class that you get by evaluating the executable's text again doesn't set id.

--no-compile-function-source removes the text. The executable is smaller and doesn't contain your source code. It still runs code from strings. In Bun.build, the option is compile: { functionSource: false }.

function add(a: number, b: number): number {
  return a + b;
}
console.log(String(add), add.name, add.length);

bun compile --no-compile-function-source ./text.ts && ./text

function add() { [native code] } add 2

Code that reads parameter names out of that string, as some dependency injection libraries do, finds none.

A library that reads the text of your functions can also decide differently on the text of your file than on what the transpiler printed. Elysia reads a handler to find out whether it needs the request body, and it doesn't follow a variable that holds the context: after const c = context; return handle(c), context.body is undefined in an executable. bun run prints that handler as return handle(context), which Elysia does follow. Pass context itself.

Error messages#

The class of an error, its line and its stack are the same as under bun run. Where bun run quotes your source in a message, an executable quotes less of it.

const o: any = { a: null };
try {
  o.b();
} catch (error) {
  console.log(String(error));
}
try {
  o.b(1, 2);
} catch (error) {
  console.log(String(error));
}
try {
  new o.b();
} catch (error) {
  console.log(String(error));
}
try {
  o.a.c;
} catch (error) {
  console.log(String(error));
}
try {
  o.a.c = 1;
} catch (error) {
  console.log(String(error));
}

bun messages.ts

TypeError: o.b is not a function. (In 'o.b()', 'o.b' is undefined)
TypeError: o.b is not a function. (In 'o.b(1, 2)', 'o.b' is undefined)
TypeError: undefined is not a constructor (evaluating 'new o.b')
TypeError: null is not an object (evaluating 'o.a.c')
TypeError: null is not an object (evaluating 'o.a.c = 1')

bun compile ./messages.ts && ./messages

TypeError: o.b is not a function. (In 'o.b()', 'o.b' is undefined)
TypeError: o.b is not a function. (In 'o.b()', 'o.b' is undefined)
TypeError: undefined is not a constructor (evaluating 'new o.b')
TypeError: null is not an object (evaluating 'null.c')
TypeError: null is not an object (evaluating 'null.c')

An executable doesn't hold the text of each expression. It keeps what you called where that consists of names, this, super and keys in brackets, up to 80 characters. A callee that's more than that has no name in the message: f()() says 5 is not a function, and so does a call with spread arguments.

A method that you call on more than that has its own name alone: make().get(), new Late(1).get() and [1].get() all say get is not a function. (In 'get()', 'get' is undefined), where bun run says make().get is not a function. (In 'make().get()', 'make().get' is undefined). So does a method that many places call on different objects: stream.destroy() can say destroy is not a function.

A tagged template is worded as a call. tag`x` says tag is not a function. (In 'tag()', 'tag' is undefined), where bun run says undefined is not a function (near '...tag`x`...').

One more message differs in an executable built with --sourcemap=external, although bun run quotes nothing in it. There, an update through a computed key, o[k] += 1, o[k]++, --o[k] or o[k] &&= 1, throws undefined is not an object when o is undefined and null is not an object when it's null, unless k is an object. bun run and every other executable say Cannot access property of undefined or null for both.

The class of the error is the same, so test error instanceof TypeError or error.name, not error.message. A service that groups errors by message, such as Sentry, sees new groups.

When bun run prints an error, it prints the lines of your file around it first, with a caret under the place. An executable prints the message and the stack trace without those lines. It doesn't hold the text of your files, and it never opens a file to show you one: what lies on the disk under that name may not be what was compiled. The stack trace has the lines and columns of your sources, and the originalLine and originalColumn of an error are its line and column. bun run --aot runs your files where they are, so it prints the lines.

Class names from computed keys#

A class without a name takes the name of the property that it's assigned to. With a computed key, bun run sets that name after the static fields of the class have run, and not at all if one of them has read name. An executable sets it first, as the ECMAScript specification says.

function create(key: string) {
  return {
    [key]: class {
      static label = this.name;
    },
  }[key]!;
}

const Shape = create("Shape");
console.log([Shape.label, Shape.name]);

bun compile ./names.ts && ./names

[ "Shape", "Shape" ]

bun names.ts prints [ "", "" ].

Function names from local variables#

A function or a class without a name takes the name of the variable that it's assigned to. Inside a function or a block, Bun's transpiler replaces a let or const that is used once, in the next statement, with its value. Under bun run the function then never reaches a variable, so it has no name. An executable gives it the name, as the ECMAScript specification says. The same holds for a function that is declared in a block, such as the body of an if or of a loop, and used once in the first statement of that block.

function create() {
  const double = (x: number) => x * 2;
  return double;
}

console.log([create().name]);

bun compile ./locals.ts && ./locals

[ "double" ]

bun locals.ts prints [ "" ]. A var, and a variable at the top level of a file, give the name in both.

Raw strings of tagged templates#

String.raw, and strings.raw in a tag function, give you the text of a template as you wrote it.

console.log(String.raw`é`, String.raw`é`.length);

bun compile ./raw.ts && ./raw

é 1

That's what the ECMAScript specification says. bun raw.ts prints é 6, because Bun's transpiler rewrites every character above U+007F in a tagged template to an escape before the file runs. The cooked strings, strings[0] in a tag function, are the same in both.

Sloppy-mode code#

This section applies to CommonJS files without "use strict" at the top. ES modules and TypeScript files with import or export are always strict.

with statements work, and so does a direct eval that declares variables.

Flags on process#

Bun itself looks at five properties of process: noDeprecation, throwDeprecation, traceDeprecation, traceProcessWarnings and domain. In a compiled executable, Bun only reads them as own properties of process. process.noDeprecation = true and BUN_OPTIONS="--no-deprecation" work as before. EventEmitter.prototype.noDeprecation = true doesn't: Bun ignores it, and still warns. util.inspect reads its styles the same way: only the object's own keys count.

Memory#

• Each thread can have 32 GB of objects. References between objects take 32 bits. Objects and small arrays count toward the limit. The characters of strings, large arrays, ArrayBuffers and typed arrays don't. Each Worker has a limit of its own. Where the address space of the process is limited (ulimit -v), objects take address space as they need it and share the limit with everything else in the process. Address space that objects have taken stays reserved for objects until the process exits. A thread that goes over it gets a RangeError whose message starts with "Out of memory" and names the limit and the option that removes it. A thread that stays just under the limit gets the same error once four garbage collections in a row have each freed less than 1/64 of the heap. Otherwise it would spend nearly all of its time collecting garbage. Your code can catch it. It is thrown where it allocates, in JSON.parse and structuredClone, or at the next function call that checks the stack. One case is left: a loop that allocates inside a try of its own function, or that the compiler has inlined into one, and that calls no function gets no error there, and ends the process with an out-of-memory error once memory is used up, or after 16 such collections in a row. In a Worker it ends that Worker alone: its parent gets an error event with the RangeError, and the exit code is 1. Move the loop into a function of its own. bun compile --aot-huge-heap compiles with 64-bit references, which removes the limit. The executable then uses more memory and runs slower.
• Where the address space is limited, new Worker() throws a TypeError when there is no room for another thread. If another Worker that the same thread started is ending at that moment, the constructor returns, and the new Worker starts once that one has ended. One new Worker can wait for each one that is ending. If there is still no room then, it gets an error event with the same TypeError and closes with code 1.
• A local variable stops keeping its value alive after its last use, even if the function is still waiting at an await. In an async function or a generator, parameters are the exception: whatever the names in the parameter list hold, and this, stay alive until the function ends, as under bun run. In any other function, a parameter is like a local variable. Under bun run, a local variable that a closure captures lives as long as the function's other variables. So if a FinalizationRegistry is in a local variable that you never touch again, it can be collected while the function waits, and its callback never runs. Keep the registry at module level.
• A variable or property that nothing reads doesn't keep its value alive. The compiler removes it along with the stores into it. If you park an object in a module-level variable only so that a WeakRef to it keeps answering, or so that its FinalizationRegistry callback doesn't run yet, read that variable somewhere.

Platforms#

bun compile compiles for arm64 and x64, on the platform that runs the build.