Bun esbuild

esbuild

> Migration guide from esbuild to Bun's bundler

Bun's bundler API is inspired heavily by esbuild. 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.

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

With a performance-minded API coupled with the extensively optimized Zig-based JS/TS parser, Bun's bundler is 1.75x faster than esbuild on esbuild's three.js benchmark.

Bundling 10 copies of three.js from scratch, with sourcemaps and minification

CLI API

Bun and esbuild both provide a command-line interface.

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}

esbuild

esbuild --outdir=out --bundle

bun

bun build --outdir=out

In Bun's CLI, simple boolean flags like `--minify` do not accept an argument. Other flags like `--outdir ` 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`.

| esbuild                | bun build                  | Notes                                                                                                                                                                                                                                                                                                                                                                   |
| ---------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--bundle`             | n/a                        | Bun always bundles, use `--no-bundle` to disable this behavior.                                                                                                                                                                                                                                                                                                         |
| `--define:K=V`         | `--define K=V`             | Small syntax difference; no colon.`esbuild --define:foo=bar``bun build --define foo=bar`                                                                                                                                                                                                                                                                    |
| `--external:`     | `--external `         | Small syntax difference; no colon.`esbuild --external:react``bun build --external react`                                                                                                                                                                                                                                                                    |
| `--format`             | `--format`                 | Bun supports `"esm"` and `"cjs"` currently, but more module formats are planned. esbuild defaults to `"iife"`.                                                                                                                                                                                                                                                          |
| `--loader:.ext=loader` | `--loader .ext:loader`     | Bun supports a different set of built-in loaders than esbuild; see 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.`esbuild app.ts --bundle --loader:.svg=text``bun build app.ts --loader .svg:text` |
| `--minify`             | `--minify`                 | No differences                                                                                                                                                                                                                                                                                                                                                          |
| `--outdir`             | `--outdir`                 | No differences                                                                                                                                                                                                                                                                                                                                                          |
| `--outfile`            | `--outfile`                | No differences                                                                                                                                                                                                                                                                                                                                                          |
| `--packages`           | `--packages`               | No differences                                                                                                                                                                                                                                                                                                                                                          |
| `--platform`           | `--target`                 | Renamed to `--target` for consistency with tsconfig. Does not support `neutral`.                                                                                                                                                                                                                                                                                        |
| `--serve`              | n/a                        | Not applicable                                                                                                                                                                                                                                                                                                                                                          |
| `--sourcemap`          | `--sourcemap`              | No differences                                                                                                                                                                                                                                                                                                                                                          |
| `--splitting`          | `--splitting`              | No differences                                                                                                                                                                                                                                                                                                                                                          |
| `--target`             | n/a                        | Not supported. Bun's bundler performs no syntactic down-leveling at this time.                                                                                                                                                                                                                                                                                          |
| `--watch`              | `--watch`                  | No differences                                                                                                                                                                                                                                                                                                                                                          |
| `--allow-overwrite`    | n/a                        | Overwriting is never allowed                                                                                                                                                                                                                                                                                                                                            |
| `--analyze`            | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                           |
| `--asset-names`        | `--asset-naming`           | Renamed for consistency with naming in JS API                                                                                                                                                                                                                                                                                                                           |
| `--banner`             | `--banner`                 | Only applies to js bundles                                                                                                                                                                                                                                                                                                                                              |
| `--footer`             | `--footer`                 | Only applies to js bundles                                                                                                                                                                                                                                                                                                                                              |
| `--certfile`           | n/a                        | Not applicable                                                                                                                                                                                                                                                                                                                                                          |
| `--charset=utf8`       | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                           |
| `--chunk-names`        | `--chunk-naming`           | Renamed for consistency with naming in JS API                                                                                                                                                                                                                                                                                                                           |
| `--color`              | n/a                        | Always enabled                                                                                                                                                                                                                                                                                                                                                          |
| `--drop`               | `--drop`                   |                                                                                                                                                                                                                                                                                                                                                                         |
| n/a                    | `--feature`                | Bun-specific. Enable feature flags for compile-time dead-code elimination via `import { feature } from "bun:bundle"`                                                                                                                                                                                                                                                    |
| `--entry-names`        | `--entry-naming`           | Renamed for consistency with naming in JS API                                                                                                                                                                                                                                                                                                                           |
| `--global-name`        | n/a                        | Not applicable, Bun does not support `iife` output at this time                                                                                                                                                                                                                                                                                                         |
| `--ignore-annotations` | `--ignore-dce-annotations` |                                                                                                                                                                                                                                                                                                                                                                         |
| `--inject`             | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                           |
| `--jsx`                | `--jsx-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`. The bundler does not support `preserve`.                                                                                                              |
| `--jsx-factory`        | `--jsx-factory`            |

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jarle](https://github.com/jarle)
- **Source:** [jarle/bun-skills](https://github.com/jarle/bun-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.