# Compatibility
> What works as it does under bun run, what differs on purpose, and what isn't available in an executable built with bun compile
Ahead-of-time compilation is experimental.
An executable built with [`bun compile`](/compiler/aot) 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](/compiler/types#when-a-value-doesnt-match-its-type), and the program behaves as it does under `bun run`.
If an error message sent you here:
| The message | See |
| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `Cannot assign to ... because built-in objects are read-only` | [Built-in objects are read-only](#built-in-objects-are-read-only) |
| `Cannot delete ... because built-in objects are read-only` | [Built-in objects are read-only](#built-in-objects-are-read-only) |
| `Cannot change the prototype of ... because built-in objects are read-only` | [Built-in objects are read-only](#built-in-objects-are-read-only) |
| `Cannot declare 'Math': compiled code treats the global 'Math' as a constant ...` | [Built-in objects are read-only](#built-in-objects-are-read-only) |
| `Cannot load '...': it isn't in this executable` | [Code that isn't in the executable](#code-that-isnt-in-the-executable) |
| `Cannot load '...': this executable can't load a module from a dynamic path` | [Code from strings](#code-from-strings) |
| `Code generation from strings disallowed for this context: the compiler couldn't tell ...` | [Code from strings](#code-from-strings) |
| `... was not compiled into this executable because your code never uses it` | [Code from strings](#code-from-strings) |
| `Cannot replace a loader in Module._extensions: imports in this executable were resolved ...` | [Loader hooks](#loader-hooks) |
| `... can't be used with this executable` | [Options that load code](#options-that-load-code) |
| `... was compiled ahead of time and can't be imported inside a ShadowRealm` | [What isn't available](#what-isnt-available) |
| `super() cannot be called from direct eval` | [What isn't available](#what-isnt-available) |
| Anything else | [Troubleshooting](/compiler/troubleshooting) |
## What works the same
- npm packages, with or without types, except for [a few](#libraries-that-are-known-not-to-work)
- ES modules, CommonJS, `require()`, `import()` of a string literal, top-level `await`
- every `node:` and `bun:` module
- [Workers](#workers) and [native addons](#native-addons)
- [`eval` and `new Function`](#code-from-strings), in the interpreter
- [macros](/bundler/macros)
- [plugins of `Bun.build`](#plugins-and-build-options), `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
| Area | `bun run` | Compiled |
| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Type errors](/compiler/aot#type-errors-stop-the-build) | `bun build` ignores them | They stop the build |
| [The version of TypeScript](#type-errors-are-typescript-7s) | Types are never checked | TypeScript 7's errors, whichever version you have installed |
| [A `.ts` file without `import` or `export`](#files-without-import-or-export) | Its variables aren't global. Another file that reads one throws | The other file is a type error, also where `tsc` takes the file for a script |
| [Built-in objects](#built-in-objects-are-read-only) | Can be changed | Can be extended. Their existing members can't be replaced |
| [Seven Bun classes](#request-response-and-five-other-classes) | Their prototypes can be changed | Their prototypes are read-only. Subclasses work |
| [Code from strings](#code-from-strings) | The JIT compiles it | Bun interprets it |
| [WebAssembly](#webassembly) | The JIT compiles it | A `.wasm` file that you import is compiled. Bun interprets any other module |
| [Dynamic imports](#dynamic-imports) | Loaded from disk | Entry points are found in the executable. Other code throws. Data files load |
| Exports of compiled modules | `spyOn(namespace, "f")` from `bun:test` replaces the export | Throws a `TypeError`. An export of a module loaded from disk at run time can still be spied on |
| [The module cache](#the-module-cache) | Lists every module that has run. `delete` makes one run again | Doesn't list the modules of the executable. Each runs at most once |
| [A CommonJS module that threw](#the-module-cache) | The next `require()` runs it again | The next `require()` throws the same error |
| [Loader hooks](#loader-hooks) | `Module.prototype.require = f` sees every `require()` | It sees a `require()` of a dynamic path. A constant path was resolved at build time |
| [`require.main`, `module.children`, `module.parent`](#module-objects) | Lead from any module object to every other | The same if some file of your program names one of them. Otherwise `undefined` for everybody |
| [`export *` of a CommonJS module](#re-exports-of-commonjs-modules) | The namespace object follows the specification | It differs in one rare case |
| The namespace object of an ES module that a CommonJS module has required | `Object.isExtensible()` says `true`, `Object.isSealed()` `false` | `false` and `true`, as for every other namespace object. In both, nothing can be added to it |
| [Some error messages](#error-messages) | Quote your source: `(evaluating 'o.a.c')` | Quote what you called, the name of the property, `(evaluating 'null.c')`, or nothing |
| [The lines of code under an error](#error-messages) | Printed above the message, with a caret | Not printed. The message and the stack trace are the same |
| The `line`, `column` and `stack` of a `DOMException`. Where a module disposes a `using` | Places in the text that runs | Places in the source file |
| The stack of an error that the parameters of an async function with an `await` throw | Doesn't list the function | Lists the function |
| The stack of an error from the setup of an `enum`, a `namespace` or a decorated class | Has an `` frame for the declaration | Has no such frame. The function around the declaration is listed at the place that ran |
| The stack of an error from a field of a class with a decorated field and no constructor | Lists `new` and the name of the class | Doesn't, as for a class without decorators |
| The stack of a `RangeError` from `new Array(-1)`, where `Array` is a variable of your own | Often doesn't list `Array`, if the variable holds the built-in | Lists `Array`, like any other function that a variable holds |
| The frames printed for an error that leaves a generator and that nobody catches | Don't list the generator | List the generator |
| A closure that runs while another closure of the same function gets a `displayName` | Stack traces list it under its own name | They list it under the `displayName` until it returns, and a callback of `map()` or `forEach()` until that call ends. Closures that are called later are listed under their own names |
| Closures of one function that `new Function()` code or a `Proxy` trap names one by one | Stack traces list each closure under its own name | Where the build knows which function a call runs, they list each of the closures under the name that was set last |
| A closure that is named after it threw, before `stack` is read, where the build can't see | The stack lists it under the new name | The first time in a program, the stack lists it under the name that it had when it threw. Later ones are listed under the new name |
| [The name of a class under a computed key](#class-names-from-computed-keys) | Set after the static fields ran, and skipped if they read `name` | Set before the static fields run |
| [The name of a function in a local variable](#function-names-from-local-variables) | Empty, if the variable is a `let` or `const` that is used once | The name of the variable |
| The name of a function or a class behind `export default` that has no name of its own | The file's name and `_default`. A class: `starDefault` in traces | `default`, in `name` and in stack traces |
| [Raw strings of tagged templates](#raw-strings-of-tagged-templates) | Characters outside ASCII come back as escapes | The text as you wrote it |
| [`Function.prototype.toString()`](#functionprototypetostring) | What the transpiler printed | The text of your file, without the types |
| Code nested more than 2,000 levels deep: calls in calls, an `else if` behind 2,000 others | Runs, as deep as the stack allows | The build stops with `TS100301` at the code, or with `TS100060` for a file that is too deep to read. A sum or an `&&` of any number of operands isn't nested |
| `JSON.stringify()` of objects nested more than 40,000 deep | Throws a `RangeError` | Writes the text where the types name the objects, as deep as the stack allows |
| `JSON.stringify()` of an object that holds a string of 358 million characters or more | Writes the text, or throws a `RangeError` for some objects | Writes the text for more of them, as Node.js does: for an object that also holds a `Date`, and for an instance of a class declared in a function, where `bun run` throws once the function has run a few times |
| `process.default`, `Bun.default` | `undefined` | The object itself |
| The own keys of `Object`, copied and then listed, behind a `for (key in Bun)` loop | `setPrototypeOf`, `defineProperties` stand ahead of the others | In the place that they have without the loop, unless the program names `Bun.$`. The loop asks for `$`, `bun run` makes `Bun.$` for that, and the code that makes it reads the two. A member of `Bun` that nothing names isn't made |
| [Sloppy-mode code](#sloppy-mode-code) | `f.caller`, `f.arguments` | Both are `null` |
| [Sloppy-mode code](#sloppy-mode-code) | `getFunction()` of a call site answers the function | `undefined`, as for a strict function, and as in an executable built without `--aot` |
| [A `.cjs` file loaded with `import`](#sloppy-mode-code) | Strict, if nothing in its text shows that it's CommonJS | Sloppy, as in Node.js |
| A `.mjs` file that calls `require()` and has no `import` or `export`, behind an `import` | Runs ahead of the files that are imported before it | Runs in the order of the imports, as in an executable built without `--aot` |
| `require()` of modules that an `import()` is loading, while the loader fetches others | The others run a few promise jobs behind the `require()` | In some turns they run inside the `require()`, as under `bun run` once nothing else is left to fetch. Each module runs once, behind what it imports. The language leaves open when a load ends |
| `require()` of such modules where one of them awaits, so that `require()` throws | The first of them begins, then `require()` throws | In some turns `require()` throws first and they begin behind the error. Each module runs once, behind what it imports |
| `import()` of a module that another `import()` is still loading | Settles in a turn that changes from run to run | Settles in the same turn in every run. Each module runs once, behind what it imports. The language leaves open when a load ends |
| `require.resolve("./x")` of a file that isn't in the executable | Looks in the folder of the file that asks | Looks in that folder below the working directory if it's there, and else in the working directory, where an executable built without `--aot` looks |
| `__esModule` of a CommonJS file, stored by a file that is imported behind it | An `import` goes by what it was when the file had run | An `import` goes by what it is when every CommonJS file that the module imports has run, as in `bun build --compile` and Node.js |
| `import { x }`, where a CommonJS file has a getter for `x` that isn't enumerable | The import fails: the file has no export named `x` | Finds `x` if the getter only returns a member of another file, as in `return other.x`, and the text of the file shows all of its exports, as in an executable built without `--aot`. Otherwise the import fails |
| A CommonJS file that is imported back while a `require()` of an ES module runs it | Some importers keep its exports of that moment, later ones don't | All importers read the same exports: those of that moment while the file runs, and what it has exported at its end from then on. `import()` gives the namespace object that `import * as` gave |
| `process.nextTick()` in a file that an `import` loads, with more files still to run | When the tick runs hangs on when the other files were read | Each file runs once, in the order of the imports, and ticks keep their order. A tick may run behind a file that it runs ahead of under `bun run`, or ahead of the importing module where it runs behind it under `bun run` |
| `import` of a package whose package.json has both `"module"` and `"main"` | Loads the file that `"main"` names | Loads the file that `"module"` names, as in an executable built without `--aot`. If the program also loads the package with `require()`, both load the file that `"main"` names |
| `undefined[key] = value`, and the same on `null` | Converts the key, which can run your code, then throws | Throws first, as the specification says. The key's `toString()` never runs |
| `arguments` in a string that `eval` runs in a generator or an async function | A `ReferenceError`, or those of a function further out | Those of the generator or async function. The same under `bun run` if its own code names `arguments`, or if an async function has no `await` |
| `eval(text)` in a computed key or the `extends` clause of a class, in sloppy-mode code | Runs the text as sloppy-mode code | Runs it as strict code, like the rest of the class, as Node.js and an executable built without `--aot` do |
| `function (a, b = eval("var x = 1")) {}` in sloppy-mode code where `x` exists further out | The text stores to the outer `x` | The text makes an `x` for this call, as in Node.js. The body reads it, `delete x` removes it, and the outer `x` keeps its value |
| `function (a, ...b) { eval("var a = 4"); }`, or a pattern for `...b`, in sloppy-mode code | The body keeps reading the parameter `a` | The body reads the `a` of the string from then on, as in Node.js: `4` here, `undefined` after `eval("var a")` |
| `function* (a, f = () => a) { var a = 2; }`, and the same in an async function | `f` reads and stores to the `a` of the body | `f` reads and stores to the parameter, which is another variable than the `var`, as in Node.js and as in a function that is neither |
| `x = f() + ""` in a `try`, where `f()` returns a symbol, so that the `+` throws | `x` holds the symbol in the `catch` and after it | `x` keeps the value that it had, as in Node.js |
| `await import("bun:main")` at the top level of the entry point, or of a file it imports | Stays pending, and the process waits | Loads a module without exports, and the file continues |
| `import("./a.js", options)` with `{ with: { type: "text" } }` held in a variable | The text of the file | The module, as in an executable built without `--aot`. With the options written in the call, the text |
| `import("node:path", { with: { type: "json" } })`: a built-in module with a type | Another namespace object, with the same members | The namespace object that `import("node:path")` gives. A built-in module is one module, whatever the attributes say |
| `require()` by `const { platform } = process` where `process.platform` was assigned | Loads the file of the assigned name | Throws `MODULE_NOT_FOUND`. The executable contains the file for the platform that it's built for. Pass the other file as another entry point |
| `this` at the top level of a file with an `import`, an `export` or a top-level `await` | `null` | `undefined`, as the specification says |
| `this` at the top of a CommonJS file, in `eval("this")` or behind `// @bun @bun-cjs` | The `module` object | `module.exports`, which is what Node.js passes to a CommonJS file, and what a `this` that is written in the file is under `bun run` too |
| An unused read of a browser global such as `closed`, `name` or `document` | Removed. Nothing is thrown, though the global doesn't exist | Throws a `ReferenceError`, as the specification says |
| An object literal that nothing uses, with a symbol as a computed key | Throws a `TypeError` | Nothing is thrown, as the specification says |
| `Object.keys({ get a() {}, b: 1, get a() {} })`: a getter that a literal has twice | `b`, then `a` | `a`, then `b`: a key stays where it first stood, as the specification says and as in Node.js |
| `concat()` of a list with a hole, into a filled list that `Symbol.species` answers | The index is empty afterwards | What the list held there stays, as the specification says and as in Node.js |
| `delete "text".length`, `delete "text"[1]`: the length or a character of a string literal | `true` | `false`, and a `TypeError` in strict code, as the specification says |
| The name of a class with a class decorator, read before the decorators have run | `undefined` | Throws a `ReferenceError`, as the specification says |
| The computed key of a member with a decorator, with `experimentalDecorators` | Runs the key expression twice | Runs it once, as TypeScript's compiler emits it |
| `design:paramtypes` of a decorated class that has fields and no constructor | An empty list, with `useDefineForClassFields: false` | Not set, as in what TypeScript's compiler emits |
| An imported interface that only the type of a decorated member names | Throws a `SyntaxError`, with `emitDecoratorMetadata` | Runs. `design:type` is `Object`, as in what TypeScript's compiler emits |
| `export { T } from "./file"` where `T` is only a type | Throws a `SyntaxError`: the export is not found | Runs the file, as an executable built without `--aot` does |
| `namespace A.B {}` or `namespace A { /*! note */ }` with nothing but types inside | `A` is an object, and an export of the file if it is exported | There is no `A`, as in what TypeScript's compiler emits. Reading `A` as a value is a type error |
| The values of `accessor` fields in a class with no class above | Some run behind the defaults of the constructor's parameters | All run ahead of them, in the order of the members, as the values of fields do |
| `accessor a = 1;` in a subclass whose constructor has `super()` inside a statement | Throws a `ReferenceError` | Works, with or without a field beside it, as what TypeScript's compiler emits does |
| The name of `f` behind `const f = (0, () => {})` or `const f = null ?? (() => {})` | `"f"` | Empty, as in Node.js |
| The name of `f` behind `const f = { held: () => {} }.held` or `const f = [() => {}][0]` | `"f"` | `"held"`, from the key in the literal, and empty for the function out of the list, as in Node.js |
| `f.bind().name`, where `f` has its name from a computed key, as in `{ [key]() {} }` | `"bound "`, without the key | `"bound "` and the key, as in Node.js |
| An async `f` with such a name in a stack trace, behind its `await`. `spyOn(o, key).name` | ``. An empty name | The key. Node.js lists the function under it too |
| `for (const { a = a } of list)`, from the second turn on | Reads what `a` held on the turn before | Throws a `ReferenceError`, as on the first turn and as Node.js does |
| The message for `[a] = [1]; let a;`: a pattern stores to a variable ahead of its `let` | Quotes the pattern, `'[a]'`, or nothing, `''` | Names the variable, as Node.js does: `Cannot access 'a' before initialization.` |
| `{ [key]: f() }`, where `key` is an object | Calls `f` ahead of `key.toString()` | Calls `key.toString()` first, as Node.js does |
| The keys of `{ set a(v) {}, b: 1, set a(v) {} }` | `b`, `a` | `a`, `b`, as in Node.js: a key keeps its first place |
| `0 / 0` in the scope of a variable of yours named `NaN` | What the variable holds | `NaN`, as in Node.js and in an executable built without `--aot` |
| A function that a later clause of a `switch` declares, read in an earlier clause | Throws a `ReferenceError` | Is there, as in Node.js: the clauses are one block |
| `label: function f() {}` in sloppy-mode code | Nothing around the label sees `f` | The function around it sees `f`, as in Node.js |
| `super.x` in the constructor of a class that extends a `Proxy` | Throws a `TypeError` | Works, as in a method and as in Node.js |
| `[f, g][1]()`: a function called straight out of an array literal, by a constant index | `this` is `undefined`, or the global object in sloppy-mode code | `this` is the array, as in Node.js and in an executable built without `--aot` |
| `` (0, object.method)`x` ``: the tag of a template in parentheses, behind a comma | `this` is `object` | `this` is `undefined`, or the global object in sloppy-mode code, as in Node.js and as in the call `(0, object.method)()` |
| `arguments.length` behind `Object.freeze(arguments)`, where a closure reads a parameter | The number of parameters | The number of arguments, as in Node.js |
| `Object.isExtensible(ns)`, where `ns` is what `require()` returns for an ES module | `true`, and `Object.isSealed(ns)` is `false` | `false`, and `Object.isSealed(ns)` is `true`, as in Node.js and as for `import * as ns` |
| An unused read of a `let`, `const` or local class before its declaration has run | Removed. Nothing is thrown | Throws a `ReferenceError` |
| `export const B = class extends Proxy {}`, where no file imports `B` | Throws a `TypeError` where the class is made | The class is removed with the export that nothing uses. Nothing is thrown, as in an executable built without `--aot` |
| `const a = /* @__PURE__ */ f()`, where nothing reads `a` | Calls `f` | The call is removed with the variable, as in an executable built without `--aot` |
| Joining strings into one that is too long, where nothing uses the result | Throws a `RangeError`, until the JIT has optimized the function | Throws a `RangeError` every time |
| A regular expression whose groups begin a hundred million turns before it finds its match | Gives the match up and answers that there is none | Finds the match where it needs fewer turns: it begins none of which it can tell beforehand that it fails. Otherwise it gives the match up too |
| The sign and payload of a `NaN` that is read from a float view or a `DataView` | Dropped at the read, until the JIT has optimized the function | Dropped where the number leaves arithmetic and float views, as in a function that the JIT has optimized. The sign that `-x` gives it can be dropped there too, and `to[i] = from[i]` can copy the bytes |
| `"a" + symbol + f()`: a symbol in a sum of three or more operands with a string | Calls `f()`, then throws the `TypeError` | Throws the `TypeError` first. `f()` never runs |
| `{ [key]: value }`, where converting `key` to a string runs your code | Evaluates `value`, then converts `key` | Converts `key`, then evaluates `value` |
| An object literal or a class that defines the same getter or setter twice | Its key is listed where it was defined last | Its key is listed where it was defined first |
| `static { a: { break a; } }`: a `break` out of a labeled block in a `static` block | A `SyntaxError` when the file loads | Leaves the block |
| `(5).#a`: a private name read off a whole number in parentheses | A `SyntaxError` when the file loads | The file loads. The read throws a `TypeError` when it runs |
| `Level.Low ** n`, where the enum member is negative and `n` isn't a constant | A `SyntaxError` when the file loads | Computes the power |
| In sloppy-mode code: `function f(a, a) {}`, `arguments = 1`, `eval++` on a local `eval` | An error when the file loads | Runs, as in Node.js |
| `"use\x20strict"` or `("use strict")` at the top of a function that has a `var public` | An error when the file loads | Runs, as in Node.js. Only the exact text is the directive |
| `a: b: while (x) { continue a; }`: `continue` to the outer of two labels on one loop | An error when the file loads | Continues the loop, as in Node.js |
| `enum E { static }` below `"use strict"`: a member named by a reserved word | An error when the file loads | Runs, as in what TypeScript's compiler emits |
| `if (x) const enum A {}`: an `enum` as the one statement of an `if` or a loop | An error when the file loads | Runs, as in what TypeScript's compiler emits |
| `declare class C { static prototype: number }` | An error when the file loads | Runs. The declaration is erased |
| `accessor a = 1;` in a class, with `experimentalDecorators` | An error when the file loads | Runs, as in what TypeScript's compiler emits |
| `@d(x => x.#a) m() {}`: a private name in a decorator, with `experimentalDecorators` | A `SyntaxError` when the file loads | Runs, as in what TypeScript's compiler emits |
| A class with a decorator in a file with `this` at the top or `export =` | A `SyntaxError` when the file loads | Runs |
| `import require = require("./file")` in an ES module | Throws a `ReferenceError` | Imports the file under that name |
| `import { x } from "./m"; const x = 1;` below `// @ts-ignore`, where that `x` is a value | Runs. `x` is the constant | The build reports `TS2440`, which no comment turns off: both are there when the program runs, so the name is declared twice in one scope |
| `import { a as x }` and `import { b as x }` in a file with `// @ts-nocheck` | Runs. `x` is the later import | The build reports `TS2300`, which no comment turns off. In a JavaScript file `bun run` reports an error too |
| `for (using of list)`, `for await (async of list)`: loops that store to such a variable | An error when the file loads | Runs, as in Node.js |
| ``(a?.b)`x` ``, `new (a?.b)()`: an optional chain in parentheses as a tag or behind `new` | A `SyntaxError` when the file loads | Runs, as in Node.js |
| `x