Start esbuild migration guide. More docs. (#2787)

* Bundler docs updates. Start esbuild migration guide.

* Updates

* Add JS API comp

* Tweaks

* Updates

* Updates

* Updates

9 files changed, 1279 insertions, 73 deletions

diff --git a/README.md b/README.md
index dde41eee4..cc688f438 100644
--- a/README.md
+++ b/README.md
@@ -48,7 +48,7 @@ bunx cowsay 'Hello, world!'   # execute a package
 Bun supports Linux (x64 & arm64) and macOS (x64 & Apple Silicon).
 
 > **Linux users** — Kernel version 5.6 or higher is strongly recommended, but the minimum is 5.1.
-> 
+>
 > **Windows users** — Bun does not currently provide a native Windows build. We're working on this; progress can be tracked at [this issue](https://github.com/oven-sh/bun/issues/43). In the meantime, use one of the installation methods below for Windows Subsystem for Linux.
 
 ```sh
@@ -67,7 +67,6 @@ docker pull oven/bun
 docker run --rm --init --ulimit memlock=-1:-1 oven/bun
 ```
 
-
 ### Upgrade
 
 To upgrade to the latest version of Bun, run:
@@ -100,7 +99,7 @@ bun upgrade --canary
   - [Runtime](https://bun.sh/docs/runtime/index)
   - [Module resolution](https://bun.sh/docs/runtime/modules)
   - [Hot & live reloading](https://bun.sh/docs/runtime/hot)
-  - [Plugins](https://bun.sh/docs/runtime/plugins)
+  - [Plugins](https://bun.sh/docs/bundler/plugins)
 - Ecosystem
   - [Node.js](https://bun.sh/docs/ecosystem/nodejs)
   - [TypeScript](https://bun.sh/docs/ecosystem/typescript)
@@ -127,7 +126,6 @@ bun upgrade --canary
   - [DNS](https://bun.sh/docs/api/dns)
   - [Node-API](https://bun.sh/docs/api/node-api)
 
-
 ## Contributing
 
 Refer to the [Project > Development](https://bun.sh/docs/project/development) guide to start contributing to Bun.
diff --git a/docs/bundler/loaders.md b/docs/bundler/loaders.md
index 7cac75648..5c88fbc9b 100644
--- a/docs/bundler/loaders.md
+++ b/docs/bundler/loaders.md
@@ -222,7 +222,7 @@ If a value is specified for `publicPath`, the import will use value as a prefix
 
 {% callout %}
 The location and file name of the copied file is determined by the value of [`naming.asset`](/docs/cli/build#naming).
-{% callout %}
+{% /callout %}
 This loader is copied into the `outdir` as-is. The name of the copied file is determined using the value of `naming.asset`.
 
 {% details summary="Fixing TypeScript import errors" %}
@@ -232,3 +232,15 @@ If you're using TypeScript, you may get an error like this:
 // TypeScript error
 // Cannot find module './logo.svg' or its corresponding type declarations.
 ```
+
+This can be fixed by creating `*.d.ts` file anywhere in your project (any name will work) with the following contents:
+
+```ts
+declare module "*.svg" {
+  const content: string;
+  export default content;
+}
+```
+
+This tells TypeScript that any default imports from `.svg` should be treated as a string.
+{% /details %}
diff --git a/docs/bundler/migration.md b/docs/bundler/migration.md
new file mode 100644
index 000000000..260acf1ba
--- /dev/null
+++ b/docs/bundler/migration.md
@@ -0,0 +1,1127 @@
+Bun's bundler API is inspired heavily by [esbuild](https://esbuild.github.io/). Migrating to Bun's bundler from esbuild should be relatively painless. This guide will briefly explain why you might consider migrating to Bun's bundler and provide a side-by-side API comparison reference for those who are already familiar with esbuild's API.
+
+There are a few behavioral differences to note.
+
+- **Bundling by default**. Unlike esbuild, Bun _always bundles by default_. This is why the `--bundle` flag isn't necessary in the Bun example. To transpile each file individually, use [`Bun.Transpiler`](/docs/api/transpiler.md).
+- **It's just a bundler**. Unlike esbuild, Bun's bundler does not include a built-in development server or file watcher. It's just a bundler. The bundler is intended for use in conjunction with `Bun.serve` and other runtime APIs to achieve the same effect. As such, all options relating to HTTP/file watching are not applicable.
+
+## Performance
+
+This is the simplest reason to migrate to Bun's bundler. With an performance-minded API inspired by esbuild coupled with the extensively optimized Zig-based JS/TS parser, Bun's bundler is roughly 50% faster than esbuild on most benchmarks.
+
+IMAGE HERE
+
+## CLI API
+
+Bun and esbuild both provide a command-line interface.
+
+```bash
+$ esbuild <entrypoint> --outdir=out --bundle
+$ bun build <entrypoint> --outdir=out
+```
+
+In Bun's CLI, simple boolean flags like `--minify` do not accept an argument. Other flags like `--outdir <path>` do accept an argument; these flags can be written as `--outdir out` or `--outdir=out`. Some flags like `--define` can be specified several times: `--define foo=bar --define bar=baz`.
+
+{% table %}
+
+- `esbuild`
+- `bun build`
+
+---
+
+- `--bundle`
+- n/a
+- Not necessary, `bun build` always bundles.
+
+---
+
+- `--define:K=V`
+- `--define K=V`
+- Small syntax difference; no colon.
+
+  ```bash
+  $ esbuild --define:foo=bar
+  $ bun build --define foo=bar
+  ```
+
+---
+
+- `--external:<pkg>`
+- `--external <pkg>`
+- Small syntax difference; no colon.
+
+  ```bash
+  $ esbuild --external:react
+  $ bun build --external react
+  ```
+
+---
+
+- `--format`
+- `--format`
+- Bun only supports `"esm"` currently but other module formats are planned. esbuild defaults to `"iife"`.
+
+---
+
+- `--loader`
+- `--loader`
+- Bun supports a different set of built-in loaders than esbuild; see [Bundler > Loaders](/docs/bundler/loaders) for a complete reference. The esbuild loaders `dataurl`, `binary`, `base64`, `copy`, and `empty` are not yet implemented.
+
+  The syntax for `--loader` is slightly different.
+
+  ```bash
+  $ esbuild app.ts --bundle --loader:.svg=text
+  $ bun build app.ts --loader .svg:text
+  ```
+
+---
+
+- `--minify`
+- `--minify`
+- No differences
+
+---
+
+- `--outdir`
+- `--outdir`
+- No differences
+
+---
+
+- `--outfile`
+- `--outfile`
+
+---
+
+- `--packages`
+- n/a
+- Not supported
+
+---
+
+- `--platform`
+- `--target`
+- Renamed to `--target` for consistency with tsconfig
+
+---
+
+- `--serve`
+- n/a
+- Not applicable
+
+---
+
+- `--sourcemap`
+- `--sourcemap`
+- No differences
+
+---
+
+- `--splitting`
+- `--splitting`
+- No differences
+
+---
+
+- `--target`
+- n/a
+- No supported. Bun's bundler performs no syntactic downleveling at this time.
+
+---
+
+- `--watch`
+- n/a
+- Not applicable.
+
+---
+
+- `--allow-overwrite`
+- n/a
+- Overwriting is always allowed
+
+---
+
+- `--analyze`
+- n/a
+- Not supported. Use `--manifest` to generate a manifest file.
+
+---
+
+- `--asset-names`
+- `--asset-naming`
+- Renamed for consistency with `naming` in JS API
+
+---
+
+- `--banner`
+- n/a
+- Not supported
+
+---
+
+- `--certfile`
+- n/a
+- Not applicable, Bun's bundler does
+
+---
+
+- `--charset=utf8`
+- n/a
+- Not supported
+
+---
+
+- `--chunk-names`
+- `--chunk-naming`
+- Renamed for consistency with `naming` in JS API
+
+---
+
+- `--color`
+- n/a
+- Always enabled
+
+---
+
+- `--drop`
+- n/a
+- Not supported
+
+---
+
+- `--entry-names`
+- `--entry-naming`
+- Renamed for consistency with `naming` in JS API
+
+---
+
+- `--footer`
+- n/a
+- Not supported
+
+---
+
+- `--global-name`
+- n/a
+- Not applicable, Bun does not support `iife` output at this time.
+
+---
+
+- `--ignore-annotations`
+- n/a
+- Not supported
+
+---
+
+- `--inject`
+- n/a
+- Not supported
+
+---
+
+- `--jsx`
+- `--jsx-runtime <runtime>`
+- Supports `"automatic"` (uses `jsx` transform) and `"classic"` (uses `React.createElement`)
+
+---
+
+- `--jsx-dev`
+- n/a
+- Bun reads `compilerOptions.jsx` from `tsconfig.json` to determine a default. If `compilerOptions.jsx` is `"react-jsx"`, or if `NODE_ENV=production`, Bun will use the `jsx` transform. Otherwise, it uses `jsxDEV`. For any to Bun uses `jsxDEV`. The bundler does not support `preserve`.
+
+---
+
+- `--jsx-factory`
+- `--jsx-factory`
+
+---
+
+- `--jsx-fragment`
+- `--jsx-fragment`
+
+---
+
+- `--jsx-import-source`
+- `--jsx-import-source`
+
+---
+
+- `--jsx-side-effects`
+- n/a
+- JSX is always assumed to be side-effect-free.
+
+---
+
+- `--keep-names`
+- n/a
+- Not supported
+
+---
+
+- `--keyfile`
+- n/a
+- Not applicable
+
+---
+
+- `--legal-comments`
+- n/a
+- Not supported
+
+---
+
+- `--log-level`
+- n/a
+- Not supported. This can be set in `bunfig.toml` as `logLevel`.
+
+---
+
+- `--log-limit`
+- n/a
+- Not supported
+
+---
+
+- `--log-override:X=Y`
+- n/a
+- Not supported
+
+---
+
+- `--main-fields`
+- n/a
+- Not supported
+
+---
+
+- `--mangle-cache`
+- n/a
+- Not supported
+
+---
+
+- `--mangle-props`
+- n/a
+- Not supported
+
+---
+
+- `--mangle-quoted`
+- n/a
+- Not supported
+
+---
+
+- `--metafile`
+- `--manifest`
+
+---
+
+- `--minify-whitespace`
+- `--minify-whitespace`
+
+---
+
+- `--minify-identifiers`
+- `--minify-identifiers`
+
+---
+
+- `--minify-syntax`
+- `--minify-syntax`
+
+---
+
+- `--out-extension`
+- n/a
+- Not supported
+
+---
+
+- `--outbase`
+- `--root`
+- Not supported
+
+---
+
+- `--preserve-symlinks`
+- n/a
+- Not supported
+
+---
+
+- `--public-path`
+- `--public-path`
+
+---
+
+- `--pure`
+- n/a
+- Not supported
+
+---
+
+- `--reserve-props`
+- n/a
+- Not supported
+
+---
+
+- `--resolve-extensions`
+- n/a
+- Not supported
+
+---
+
+- `--servedir`
+- n/a
+- Not applicable
+
+---
+
+- `--source-root`
+- n/a
+- Not supported
+
+---
+
+- `--sourcefile`
+- n/a
+- Not supported. Bun does not support `stdin` input yet.
+
+---
+
+- `--sourcemap`
+- `--sourcemap`
+- No differences
+
+---
+
+- `--sources-content`
+- n/a
+- Not supported
+
+---
+
+- `--supported`
+- n/a
+- Not supported
+
+---
+
+- `--tree-shaking`
+- n/a
+- Always `true`
+
+---
+
+- `--tsconfig`
+- `--tsconfig-override`
+
+---
+
+- `--version`
+- n/a
+- Run `bun --version` to see the version of Bun.
+
+{% /table %}
+
+## JavaScript API
+
+{% table %}
+
+- `esbuild.build()`
+- `Bun.build()`
+
+---
+
+- `absWorkingDir`
+- n/a
+- Always set to `process.cwd()`
+
+---
+
+- `alias`
+- n/a
+- Not supported
+
+---
+
+- `allowOverwrite`
+- n/a
+- Always `true`
+
+---
+
+- `assetNames`
+- `naming.asset`
+- Uses same templating syntax as esbuild, but `[ext]` must be included explicitly.
+
+  ```ts
+  Bun.build({
+    entrypoints: ["./index.tsx"],
+    naming: {
+      asset: "[name].[ext]",
+    },
+  });
+  ```
+
+---
+
+- `banner`
+- n/a
+- Not supported
+
+---
+
+- `bundle`
+- n/a
+- Always `true`
+
+---
+
+- `charset`
+- n/a
+- Not supported
+
+---
+
+- `chunkNames`
+- `naming.chunk`
+- Uses same templating syntax as esbuild, but `[ext]` must be included explicitly.
+
+  ```ts
+  Bun.build({
+    entrypoints: ["./index.tsx"],
+    naming: {
+      chunk: "[name].[ext]",
+    },
+  });
+  ```
+
+---
+
+- `color`
+- n/a
+- Bun returns logs in the `logs` property of the build result.
+
+---
+
+- `conditions`
+- n/a
+- Not supported. Export conditions priority is determined by `target`.
+
+---
+
+- `define`
+- `define`
+- Not supported in JS API
+
+---
+
+- `drop`
+- n/a
+- Not supported
+
+---
+
+- `entryNames`
+- `naming` or `naming.entry`
+- Bun supports a `naming` key that can either be a string or an object. Uses same templating syntax as esbuild, but `[ext]` must be included explicitly.
+
+  ```ts
+  Bun.build({
+    entrypoints: ["./index.tsx"],
+    // when string, this is equivalent to entryNames
+    naming: "[name].[ext]",
+
+    // granular naming options
+    naming: {
+      entry: "[name].[ext]",
+      asset: "[name].[ext]",
+      chunk: "[name].[ext]",
+    },
+  });
+  ```
+
+---
+
+- `entryPoints`
+- `entrypoints`
+- Capitalization difference
+
+---
+
+- `external`
+- `external`
+- No differences
+
+---
+
+- `footer`
+- n/a
+- Not supported
+
+---
+
+- `format`
+- `format`
+- Only supports `"esm"` currently. Support for `"cjs"` and `"iife"` is planned.
+
+---
+
+- `globalName`
+- n/a
+- Not supported
+
+---
+
+- `ignoreAnnotations`
+- n/a
+- Not supported
+
+---
+
+- `inject`
+- n/a
+- Not supported
+
+---
+
+- `jsx`
+- `jsx`
+- Not supported in JS API, configure in `tsconfig.json`
+
+---
+
+- `jsxDev`
+- `jsxDev`
+- Not supported in JS API, configure in `tsconfig.json`
+
+---
+
+- `jsxFactory`
+- `jsxFactory`
+- Not supported in JS API, configure in `tsconfig.json`
+
+---
+
+- `jsxFragment`
+- `jsxFragment`
+- Not supported in JS API, configure in `tsconfig.json`
+
+---
+
+- `jsxImportSource`
+- `jsxImportSource`
+- Not supported in JS API, configure in `tsconfig.json`
+
+---
+
+- `jsxSideEffects`
+- `jsxSideEffects`
+- Not supported in JS API, configure in `tsconfig.json`
+
+---
+
+- `keepNames`
+- n/a
+- Not supported
+
+---
+
+- `legalComments`
+- n/a
+- Not supported
+
+---
+
+- `loader`
+- n/a
+- Not supported in JS API
+
+---
+
+- `logLevel`
+- n/a
+- Not supported
+
+---
+
+- `logLimit`
+- n/a
+- Not supported
+
+---
+
+- `logOverride`
+- n/a
+- Not supported
+
+---
+
+- `mainFields`
+- n/a
+- Not supported
+
+---
+
+- `mangleCache`
+- n/a
+- Not supported
+
+---
+
+- `mangleProps`
+- n/a
+- Not supported
+
+---
+
+- `mangleQuoted`
+- n/a
+- Not supported
+
+---
+
+- `metafile`
+- `manifest`
+- When `manifest` is `true`, the result of `Bun.build()` will contain a `manifest` property. The manifest is compatible with esbuild's metafile format.
+
+---
+
+- `minify`
+- `minify`
+- In Bun, `minify` can be a boolean or an object.
+
+  ```ts
+  Bun.build({
+    entrypoints: ['./index.tsx'],
+    // enable all minification
+    minify: true
+
+    // granular options
+    minify: {
+      identifiers: true,
+      syntax: true,
+      whitespace: true
+    }
+  })
+  ```
+
+---
+
+- `minifyIdentifiers`
+- `minify.identifiers`
+- See `minify`
+
+---
+
+- `minifySyntax`
+- `minify.syntax`
+- See `minify`
+
+---
+
+- `minifyWhitespace`
+- `minify.whitespace`
+- See `minify`
+
+---
+
+- `nodePaths`
+- n/a
+- Not supported
+
+---
+
+- `outExtension`
+- n/a
+- Not supported
+
+---
+
+- `outbase`
+- `root`
+- Different name
+
+---
+
+- `outdir`
+- `outdir`
+- No differences
+
+---
+
+- `outfile`
+- `outfile`
+- No differences
+
+---
+
+- `packages`
+- n/a
+- Not supported, use `external`
+
+---
+
+- `platform`
+- `target`
+- Supports `"bun"`, `"node"`, and `"browser"` (the default)
+
+---
+
+- `plugins`
+- `plugins`
+- Bun's plugin API is a subset of esbuild's. Some esbuild plugins will work out of the box with Bun.
+
+---
+
+- `preserveSymlinks`
+- n/a
+- Not supported
+
+---
+
+- `publicPath`
+- `publicPath`
+- No differences
+
+---
+
+- `pure`
+- n/a
+- Not supported
+
+---
+
+- `reserveProps`
+- n/a
+- Not supported
+
+---
+
+- `resolveExtensions`
+- n/a
+- Not supported
+
+---
+
+- `sourceRoot`
+- n/a
+- Not supported
+
+---
+
+- `sourcemap`
+- `sourcemap`
+- Supports `"inline"`, `"external"`, and `"none"`
+
+---
+
+- `sourcesContent`
+- n/a
+- Not supported
+
+---
+
+- `splitting`
+- `splitting`
+- No differences
+
+---
+
+- `stdin`
+- n/a
+- Not supported
+
+---
+
+- `supported`
+- n/a
+- Not supported
+
+---
+
+- `target`
+- n/a
+- No support for syntax downleveling
+
+---
+
+- `treeShaking`
+- n/a
+- Always `true`
+
+---
+
+- `tsconfig`
+- n/a
+- Not supported
+
+---
+
+- `write`
+- n/a
+- Set to `true` if `outdir`/`outfile` is set, otherwise `false`
+
+---
+
+{% /table %}
+
+## Plugin API
+
+Bun's plugin API is designed to be esbuild compatible. Bun doesn't support esbuild's entire plugin API surface, but the core functionality is implemented. Many third-party `esbuild` plugins will work out of the box with Bun.
+
+{% callout %}
+Long term, we aim for feature parity with esbuild's API, so if something doesn't work please file an issue to help us prioritize.
+
+{% /callout %}
+
+Plugins in Bun and esbuild are defined with a `builder` object.
+
+```ts
+import type { BunPlugin } from "bun";
+
+const myPlugin: BunPlugin = {
+  name: "my-plugin",
+  setup(builder) {
+    // define plugin
+  },
+};
+```
+
+The `builder` object provides some methods for hooking into parts of the bundling process. Bun implements `onResolve` and `onLoad`; it does not yet implement the esbuild hooks `onStart`, `onEnd`, and `onDispose`, or the `initialOptions` and `resolve` utilities.
+
+```ts
+import type { BunPlugin } from "bun";
+const myPlugin: BunPlugin = {
+  name: "my-plugin",
+  setup(builder) {
+    builder.onResolve(
+      {
+        /* onResolve.options */
+      },
+      args => {
+        return {
+          /* onResolve.results */
+        };
+      },
+    );
+    builder.onLoad(
+      {
+        /* onLoad.options */
+      },
+      args => {
+        return {
+          /* onLoad.results */
+        };
+      },
+    );
+  },
+};
+```
+
+### `onResolve`
+
+#### `options`
+
+{% table %}
+
+- 🟢
+- `filter`
+
+---
+
+- 🟢
+- `namespace`
+
+{% /table %}
+
+#### `arguments`
+
+{% table %}
+
+- 🟢
+- `path`
+
+---
+
+- 🟢
+- `importer`
+
+---
+
+- 🔴
+- `namespace`
+
+---
+
+- 🔴
+- `resolveDir`
+
+---
+
+- 🔴
+- `kind`
+
+---
+
+- 🔴
+- `pluginData`
+
+{% /table %}
+
+#### `results`
+
+{% table %}
+
+- 🟢
+- `namespace`
+
+---
+
+- 🟢
+- `path`
+
+---
+
+- 🔴
+- `errors`
+
+---
+
+- 🔴
+- `external`
+
+---
+
+- 🔴
+- `pluginData`
+
+---
+
+- 🔴
+- `pluginName`
+
+---
+
+- 🔴
+- `sideEffects`
+
+---
+
+- 🔴
+- `suffix`
+
+---
+
+- 🔴
+- `warnings`
+
+---
+
+- 🔴
+- `watchDirs`
+
+---
+
+- 🔴
+- `watchFiles`
+
+{% /table %}
+
+### `onLoad`
+
+#### `options`
+
+{% table %}
+
+---
+
+- 🟢
+- `filter`
+
+---
+
+- 🟢
+- `namespace`
+
+{% /table %}
+
+#### `arguments`
+
+{% table %}
+
+---
+
+- 🟢
+- `path`
+
+---
+
+- 🔴
+- `namespace`
+
+---
+
+- 🔴
+- `suffix`
+
+---
+
+- 🔴
+- `pluginData`
+
+{% /table %}
+
+#### `results`
+
+{% table %}
+
+---
+
+- 🟢
+- `contents`
+
+---
+
+- 🟢
+- `loader`
+
+---
+
+- 🔴
+- `errors`
+
+---
+
+- 🔴
+- `pluginData`
+
+---
+
+- 🔴
+- `pluginName`
+
+---
+
+- 🔴
+- `resolveDir`
+
+---
+
+- 🔴
+- `warnings`
+
+---
+
+- 🔴
+- `watchDirs`
+
+---
+
+- 🔴
+- `watchFiles`
+
+{% /table %}
diff --git a/docs/bundler/plugins.md b/docs/bundler/plugins.md
index 68d2b3107..c652e0583 100644
--- a/docs/bundler/plugins.md
+++ b/docs/bundler/plugins.md
@@ -63,7 +63,7 @@ console.log(config);
 
 {% /details %}
 
-## Third party plugins
+## Third-party plugins
 
 By convention, third-party plugins intended for consumption should export a factory function that accepts some configuration and returns a plugin object.
 
@@ -164,7 +164,7 @@ releaseYear: 2023
 
 Note that the returned object has a `loader` property. This tells Bun which of its internal loaders should be used to handle the result. Even though we're implementing a loader for `.yaml`, the result must still be understandable by one of Bun's built-in loaders. It's loaders all the way down.
 
-In this case we're using `"object"`—a special loader (intended for use by plugins) that converts a plain JavaScript object to an equivalent ES module. Any of Bun's built-in loaders are supported; these same loaders are used by Bun internally for handling files of various extensions.
+In this case we're using `"object"`—a built-in loader (intended for use by plugins) that converts a plain JavaScript object to an equivalent ES module. Any of Bun's built-in loaders are supported; these same loaders are used by Bun internally for handling files of various kinds. The table below is a quick reference; refer to [Bundler > Loaders](/docs/bundler/loaders) for complete documentation.
 
 {% table %}
 
@@ -175,13 +175,13 @@ In this case we're using `"object"`—a special loader (intended for use by plug
 ---
 
 - `js`
-- `.js` `.mjs` `.cjs`
+- `.mjs` `.cjs`
 - Transpile to JavaScript files
 
 ---
 
 - `jsx`
-- `.jsx`
+- `.js` `.jsx`
 - Transform JSX then transpile
 
 ---
@@ -210,8 +210,20 @@ In this case we're using `"object"`—a special loader (intended for use by plug
 
 ---
 
+- `napi`
+- `.node`
+- Import a native Node.js addon
+
+---
+
+- `wasm`
+- `.wasm`
+- Import a native Node.js addon
+
+---
+
 - `object`
-- —
+- _none_
 - A special loader intended for plugins that converts a plain JavaScript object to an equivalent ES module. Each key in the object corresponds to a named export.
 
 {% /callout %}
diff --git a/docs/cli/build.md b/docs/cli/build.md
index 3ce34df1d..f205969d5 100644
--- a/docs/cli/build.md
+++ b/docs/cli/build.md
@@ -4,7 +4,7 @@
 
 Bun's fast native bundler is now in beta. It can be used via the `bun build` CLI command or the `Bun.build()` JavaScript API.
 
-{% codetabs %}
+{% codetabs group="a" %}
 
 ```ts#JavaScript
 await Bun.build({
@@ -55,7 +55,7 @@ Here, `index.tsx` is the "entrypoint" to our application. Commonly, this will be
 
 To create our bundle:
 
-{% codetabs %}
+{% codetabs group="a" %}
 
 ```ts#JavaScript
 await Bun.build({
@@ -80,7 +80,7 @@ For each file specified in `entrypoints`, Bun will generate a new bundle. This b
     └── index.js
 ```
 
-The contents of the `out/index.js` file looks something like this:
+The contents of `out/index.js` will look something like this:
 
 ```js#out/index.js
 // ...
@@ -176,6 +176,11 @@ Like the Bun runtime, the bundler supports an array of file types out of the box
   console.log(contents); // => "Hello, world!"
   ```
 
+---
+
+- `.node` `.wasm`
+- These files are supported by the Bun runtime, but during bundling they are treated as [assets](#assets).
+
 {% /table %}
 
 ### Assets
@@ -184,19 +189,14 @@ If the bundler encounters an import with an unrecognized extension, it treats th
 
 {% codetabs %}
 
-```ts#Build file
-await Bun.build({
-  entrypoints: ['./index.ts'],
-  outdir: './out'
-})
-```
-
 ```ts#Input
+// bundle entrypoint
 import logo from "./logo.svg";
 console.log(logo);
 ```
 
 ```ts#Output
+// bundled output
 var logo = "./logo-ab237dfe.svg";
 console.log(logo);
 ```
@@ -219,7 +219,7 @@ The behavior described in this table can be overridden with [plugins](/docs/bund
 
 **Required.** An array of paths corresponding to the entrypoints of our application. One bundle will be generated for each entrypoint.
 
-{% codetabs %}
+{% codetabs group="a" %}
 
 ```ts#JavaScript
 const result = await Bun.build({
@@ -242,7 +242,7 @@ $ bun build --entrypoints ./index.ts
 
 The directory where output files will be written.
 
-{% codetabs %}
+{% codetabs group="a" %}
 
 ```ts#JavaScript
 const result = await Bun.build({
@@ -283,7 +283,7 @@ When `outdir` is specified:
 
 The intended execution environment for the bundle.
 
-{% codetabs %}
+{% codetabs group="a" %}
 
 ```ts#JavaScript
 await Bun.build({
@@ -350,7 +350,7 @@ $ bun build ./index.tsx --outdir ./out --format esm
 
 Whether to enable bundling.
 
-{% codetabs %}
+{% codetabs group="a" %}
 
 ```ts#JavaScript
 await Bun.build({
@@ -369,7 +369,7 @@ $ bun build ./index.tsx --outdir ./out
 
 Set to `false` to disable bundling. Instead, files will be transpiled and individually written to `outdir`.
 
-{% codetabs %}
+{% codetabs group="a" %}
 
 ```ts#JavaScript
 await Bun.build({
@@ -389,7 +389,7 @@ $ bun build ./index.tsx --outdir ./out --no-bundling
 
 Whether to enable code splitting.
 
-{% codetabs %}
+{% codetabs group="a" %}
 
 ```ts#JavaScript
 await Bun.build({
@@ -425,7 +425,7 @@ export const shared = 'shared';
 
 To bundle `entry-a.ts` and `entry-b.ts` with code-splitting enabled:
 
-{% codetabs %}
+{% codetabs group="a" %}
 
 ```ts#JavaScript
 await Bun.build({
@@ -461,7 +461,7 @@ The generated `chunk-2fce6291bf86559d.js` file contains the shared code. To avoi
 
 A list of plugins to use during bundling.
 
-{% codetabs %}
+{% codetabs group="a" %}
 
 ```ts#JavaScript
 await Bun.build({
@@ -544,18 +544,18 @@ By design, the manifest is a simple JSON object that can easily be serialized or
 
 Specifies the type of sourcemap to generate.
 
-{% codetabs %}
+{% codetabs group="a" %}
 
 ```ts#JavaScript
 await Bun.build({
   entrypoints: ['./index.tsx'],
   outdir: './out',
-  sourcemap: "inline", // default "none"
+  sourcemap: "external", // default "none"
 })
 ```
 
 ```bash#CLI
-$ bun build ./index.tsx --outdir ./out --sourcemap=inline
+$ bun build ./index.tsx --outdir ./out --sourcemap=external
 ```
 
 {% /codetabs %}
@@ -570,7 +570,13 @@ $ bun build ./index.tsx --outdir ./out --sourcemap=inline
 ---
 
 - `"inline"`
-- A sourcemap is generated and appended to the end of the generated bundle as a base64 payload inside a `//# sourceMappingURL=` comment.
+- A sourcemap is generated and appended to the end of the generated bundle as a base64 payload.
+
+  ```ts
+  // <bundled code here>
+
+  //# sourceMappingURL=data:application/json;base64,<encoded sourcemap here>
+  ```
 
 ---
 
@@ -579,6 +585,20 @@ $ bun build ./index.tsx --outdir ./out --sourcemap=inline
 
 {% /table %}
 
+{% callout %}
+
+Generated bundles contain a [debug id](https://sentry.engineering/blog/the-case-for-debug-ids) that can be used to associate a bundle with its corresponding sourcemap. This `debugId` is added as a comment at the bottom of the file.
+
+```ts
+// <generated bundle code>
+
+//# debugId=<DEBUG ID>
+```
+
+The associated `*.js.map` sourcemap will be a JSON file containing an equivalent `debugId` property.
+
+{% /callout %}
+
 ### `minify`
 
 Whether to enable minification. Default `false`.
@@ -589,7 +609,7 @@ When targeting `bun`, identifiers will be minified by default.
 
 To enable all minification options:
 
-{% codetabs %}
+{% codetabs group="a" %}
 
 ```ts#JavaScript
 await Bun.build({
@@ -607,7 +627,7 @@ $ bun build ./index.tsx --outdir ./out --minify
 
 To granularly enable certain minifications:
 
-{% codetabs %}
+{% codetabs group="a" %}
 
 ```ts#JavaScript
 await Bun.build({
@@ -635,7 +655,7 @@ boolean; -->
 
 A list of import paths to consider _external_. Defaults to `[]`.
 
-{% codetabs %}
+{% codetabs group="a" %}
 
 ```ts#JavaScript
 await Bun.build({
@@ -665,7 +685,7 @@ console.log(_.upperCase(value));
 
 Normally, bundling `index.tsx` would generate a bundle containing the entire source code of the `"zod"` package. If instead, we want to leave the `import` statement as-is, we can mark it as external:
 
-{% codetabs %}
+{% codetabs group="a" %}
 
 ```ts#JavaScript
 await Bun.build({
@@ -698,7 +718,7 @@ console.log(_.upperCase(value));
 
 Customizes the generated file names. Defaults to `./[dir]/[name].[ext]`.
 
-{% codetabs %}
+{% codetabs group="a" %}
 
 ```ts#JavaScript
 await Bun.build({
@@ -773,7 +793,7 @@ For example:
 
 We can combine these tokens to create a template string. For instance, to include the hash in the generated bundle names:
 
-{% codetabs %}
+{% codetabs group="a" %}
 
 ```ts#JavaScript
 await Bun.build({
@@ -801,7 +821,7 @@ This build would result in the following file structure:
 
 When a `string` is provided for the `naming` field, it is used only for bundles _that correspond to entrypoints_. The names of [chunks](#splitting) and copied assets are not affected. Using the JavaScript API, separate template strings can be specified for each type of generated file.
 
-{% codetabs %}
+{% codetabs group="a" %}
 
 ```ts#JavaScript
 await Bun.build({
@@ -826,7 +846,7 @@ $ bun build ./index.tsx --outdir ./out --entry-naming "[dir]/[name].[ext]" --chu
 
 The root directory of the project.
 
-{% codetabs %}
+{% codetabs group="a" %}
 
 ```ts#JavaScript
 await Bun.build({
@@ -853,7 +873,7 @@ If unspecified, it is computed to be the first common ancestor of all entrypoint
 
 We can build both entrypoints in the `pages` directory:
 
-{% codetabs %}
+{% codetabs group="a" %}
 
 ```ts#JavaScript
 await Bun.build({
@@ -884,7 +904,7 @@ Since the `pages` directory is the first common ancestor of the entrypoint files
 
 This behavior can be overridden by specifying the `root` option:
 
-{% codetabs %}
+{% codetabs group="a" %}
 
 ```ts#JavaScript
 await Bun.build({
@@ -945,7 +965,7 @@ console.log(logo);
 
 Setting `publicPath` will prefix all file paths with the specified value.
 
-{% codetabs %}
+{% codetabs group="a" %}
 
 ```ts#JavaScript
 await Bun.build({
@@ -971,32 +991,66 @@ The output file would now look something like this.
 ## Reference
 
 ```ts
-await Bun.build({
-  entrypoints: string[]; // list of file path
-  outdir?: string; // default to in-memory build
-  target?: "browser" | "bun" | "node"; // default: "browser"
-  splitting?: boolean; // default true
-  plugins?: BunPlugin[];
-  manifest?: boolean; // default false
-  external?: string[];
-  naming?: string | {
-    entry?: string; // default '[dir]/[name].[ext]'
-    chunk?: string; // default '[name]-[hash].[ext]'
-    asset?: string; // default '[name]-[hash].[ext]'
-  };
+interface Bun {
+  build(options: BuildOptions): Promise<{
+    outputs: Array<{ path: string; result: Blob | BunFile }>;
+    manifest?: BuildManifest;
+  }>;
+}
+
+interface BuildOptions {
+  entrypoints: string[]; // required
+  outdir?: string; // default: no write (in-memory only)
+  target?: "browser" | "bun" | "node"; // "browser"
+  splitting?: boolean; // true
+  plugins?: BunPlugin[]; // []
+  loader?: { [k in string]: Loader };
+  manifest?: boolean; // false
+  external?: string[]; // []
+  sourcemap?: "none" | "inline" | "external"; // "none"
+  root?: string; // computed from entrypoints
+  naming?:
+    | string
+    | {
+        entry?: string; // '[dir]/[name].[ext]'
+        chunk?: string; // '[name]-[hash].[ext]'
+        asset?: string; // '[name]-[hash].[ext]'
+      };
   publicPath?: string; // e.g. http://mydomain.com/
-  minify?: boolean | { // default false
-    identifiers?: boolean;
-    whitespace?: boolean;
-    syntax?: boolean;
+  minify?:
+    | boolean // false
+    | {
+        identifiers?: boolean;
+        whitespace?: boolean;
+        syntax?: boolean;
+      };
+}
+
+interface BuildManifest {
+  inputs: {
+    [path: string]: {
+      output: {
+        path: string;
+      };
+      imports: {
+        path: string;
+        kind: ImportKind;
+        external?: boolean;
+        asset?: boolean; // whether the import defaulted to "file" loader
+      }[];
+    };
   };
-});
+  outputs: {
+    [path: string]: {
+      type: "chunk" | "entrypoint" | "asset";
+      inputs: { path: string }[];
+      imports: {
+        path: string;
+        kind: ImportKind;
+        external?: boolean;
+      }[];
+      exports: string[];
+    };
+  };
+}
 ```
-
-<!--
-root?: string; // project root
-format?: "esm"; // later: "cjs", "iife"
-loader?: { [k in string]: Loader };
-sourcemap?: "none" | "inline" | "external"; // default: "none"
-treeshaking?: boolean;
--->
diff --git a/docs/nav.ts b/docs/nav.ts
index fcafdf25f..b0f0932e3 100644
--- a/docs/nav.ts
+++ b/docs/nav.ts
@@ -166,6 +166,9 @@ export default {
     page("bundler/plugins", "Plugins", {
       description: `Implement custom loaders and module resolution logic with Bun's plugin system.`,
     }),
+    page("bundler/migration", "Migration", {
+      description: `Guides for migrating from other bundlers to Bun.`,
+    }),
 
     divider("Test runner"),
     page("cli/test", "`bun test`", {
@@ -202,7 +205,7 @@ export default {
     page("ecosystem/stric", "Stric", {
       description: `Stric is a minimalist, fast web framework for Bun.`,
     }),
-    
+
     page("ecosystem/awesome", "Awesome", {
       href: "https://github.com/apvarun/awesome-bun",
       description: ``,
diff --git a/docs/runtime/index.md b/docs/runtime/index.md
index b835ba464..b97deb122 100644
--- a/docs/runtime/index.md
+++ b/docs/runtime/index.md
@@ -303,4 +303,4 @@ Bun exposes a set of Bun-specific APIs on the `Bun` global object and through a
 
 ## Plugins
 
-Support for additional file types can be implemented with plugins. Refer to [Runtime > Plugins](/docs/runtime/plugins) for full documentation.
+Support for additional file types can be implemented with plugins. Refer to [Runtime > Plugins](/docs/bundler/plugins) for full documentation.
diff --git a/docs/runtime/loaders.md b/docs/runtime/loaders.md
index b73350e56..a483efbec 100644
--- a/docs/runtime/loaders.md
+++ b/docs/runtime/loaders.md
@@ -82,7 +82,7 @@ $ bun run ./my-wasm-app.whatever
 
 ## Custom loaders
 
-Support for additional file types can be implemented with plugins. Refer to [Runtime > Plugins](/docs/runtime/plugins) for full documentation.
+Support for additional file types can be implemented with plugins. Refer to [Runtime > Plugins](/docs/bundler/plugins) for full documentation.
 
 <!--
 
diff --git a/packages/bun-types/bun.d.ts b/packages/bun-types/bun.d.ts
index e14118680..03c17001c 100644
--- a/packages/bun-types/bun.d.ts
+++ b/packages/bun-types/bun.d.ts
@@ -953,7 +953,7 @@ declare module "bun" {
     entrypoints: string[]; // list of file path
     outdir?: string; // output directory
     target?: Target; // default: "browser"
-    // format?: ModuleFormat; // later: "cjs", "iife"
+    format?: ModuleFormat; // later: "cjs", "iife"
 
     naming?:
       | string