> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/zhcndoc/bun/llms.txt
> Use this file to discover all available pages before exploring further.
# Migrating from esbuild
> Guide for migrating from esbuild to Bun's bundler
Bun's bundler API is heavily inspired by esbuild. Migrating from esbuild to Bun's bundler should be relatively straightforward. This document briefly explains why you might consider migrating to Bun's bundler and provides a side-by-side API reference for those already familiar with esbuild.
There are a few behavioral differences to be aware of.
**Bundling by default.** Unlike esbuild, Bun always bundles by default. That's why the `--bundle` flag doesn't appear in Bun examples. To transpile each file individually, use `Bun.Transpiler`.
**It's just a bundler.** Unlike esbuild, Bun's bundler does not include a built-in dev server or file watcher. It's just a bundler. The bundler is designed to be used with `Bun.serve` and other runtime APIs to achieve the same effect. As such, all HTTP/file-watching related options are not applicable.
## Performance
With a performance-first API and heavily optimized Zig-based JS/TS parser, Bun's bundler is 1.75x faster than esbuild on esbuild's three.js benchmark.
Bundle 10 copies of three.js from scratch with source maps and minification
## Why migrate?
Here are some reasons you might want to migrate from esbuild to Bun's bundler:
### Speed
Bun's bundler is significantly faster than esbuild, especially for large projects. The Zig-based implementation and careful optimizations make builds complete faster.
### Native features
Bun includes native support for:
* **TypeScript and JSX**: No configuration needed
* **CSS bundling**: Built-in CSS processing with modern features
* **HTML processing**: Bundle complete web applications
* **Macros**: Run code at build time
* **Framework features**: React Fast Refresh, server components
### Unified toolchain
Bun provides a complete JavaScript runtime and toolkit:
* Bundler
* Runtime
* Test runner
* Package manager
Using Bun means fewer tools to install, configure, and maintain.
### Modern defaults
Bun uses modern defaults:
* ESM by default
* Modern JavaScript syntax
* Fast native loaders for common file types
## CLI API
Both Bun and esbuild provide command-line interfaces.
```bash theme={null}
# esbuild
esbuild --outdir=out --bundle
# bun
bun build --outdir=out
```
In Bun's CLI, simple boolean flags like `--minify` don't accept arguments. Other flags with arguments like `--outdir ` accept arguments; these flags can be written as `--outdir out` or `--outdir=out`. Some flags like `--define` can be specified multiple times: `--define foo=bar --define bar=baz`.
| esbuild | bun build | Notes |
| ---------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--bundle` | N/A | Bun always bundles; use `--no-bundle` to disable. |
| `--define:K=V` | `--define K=V` | Minor syntax difference; no colon.
`esbuild --define:foo=bar`
`bun build --define foo=bar` |
| `--external:` | `--external ` | Minor syntax difference; no colon.
`esbuild --external:react`
`bun build --external react` |
| `--format` | `--format` | Bun currently supports `"esm"` and `"cjs"`, with more module formats planned. esbuild defaults to `"iife"`. |
| `--loader:.ext=loader` | `--loader .ext:loader` | Bun's set of built-in loaders differs from esbuild's; see Bundler > Loaders for complete reference. esbuild's `dataurl`, `binary`, `base64`, `copy`, and `empty` loaders are not yet implemented.
The `--loader` syntax is slightly different.
`esbuild app.ts --bundle --loader:.svg=text`
`bun build app.ts --loader .svg:text` |
| `--minify` | `--minify` | No difference |
| `--outdir` | `--outdir` | No difference |
| `--outfile` | `--outfile` | No difference |
| `--packages` | `--packages` | No difference |
| `--platform` | `--target` | Renamed to `--target` for consistency with tsconfig. Does not support `neutral`. |
| `--serve` | N/A | Not applicable |
| `--sourcemap` | `--sourcemap` | No difference |
| `--splitting` | `--splitting` | No difference |
| `--target` | N/A | Not supported. Bun's bundler currently doesn't support syntax downleveling. |
| `--watch` | `--watch` | No difference |
### Additional flags
| esbuild | bun build | Notes |
| ---------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--allow-overwrite` | N/A | Not allowed |
| `--analyze` | N/A | Not supported |
| `--asset-names` | `--asset-naming` | Renamed for consistency with JS API |
| `--banner` | `--banner` | Only applies to js bundles |
| `--footer` | `--footer` | Only applies to js bundles |
| `--charset=utf8` | N/A | Not supported |
| `--chunk-names` | `--chunk-naming` | Renamed for consistency with JS API |
| `--drop` | `--drop` | |
| N/A | `--feature` | Bun-specific. Feature flags for compile-time dead code elimination via `import { feature } from "bun:bundle"` |
| `--entry-names` | `--entry-naming` | Renamed for consistency with JS API |
| `--global-name` | N/A | Not applicable; Bun doesn't currently support `iife` output |
| `--ignore-annotations` | `--ignore-dce-annotations` | |
| `--inject` | N/A | Not supported |
| `--jsx` | `--jsx-runtime ` | Supports `"automatic"` (jsx transform) and `"classic"` (`React.createElement`) |
| `--jsx-dev` | N/A | Bun reads defaults from `tsconfig.json`'s `compilerOptions.jsx`. If the value is `"react-jsx"` or the environment variable `NODE_ENV=production`, Bun uses the jsx transform, otherwise it 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 |
| `--legal-comments` | N/A | Not supported |
| `--log-level` | N/A | Not supported; can be set via `bunfig.toml` using `logLevel` |
| `--main-fields` | N/A | Not supported |
| `--metafile` | `--metafile` | Bun supports both JSON and Markdown metafiles |
| `--minify-whitespace` | `--minify-whitespace` | |
| `--minify-identifiers` | `--minify-identifiers` | |
| `--minify-syntax` | `--minify-syntax` | |
| `--out-extension` | N/A | Not supported |
| `--outbase` | `--root` | |
| `--public-path` | `--public-path` | |
| `--sourcemap` | `--sourcemap` | No difference |
| `--tsconfig` | `--tsconfig-override` | |
## JavaScript API
| esbuild.build() | Bun.build() | Notes |
| ------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `absWorkingDir` | N/A | Always set to `process.cwd()` |
| `alias` | N/A | Not supported |
| `allowOverwrite` | N/A | Always false |
| `assetNames` | `naming.asset` | Uses the same template syntax as esbuild, but must explicitly include `[ext]`. |
| `banner` | N/A | Not supported |
| `bundle` | N/A | Always on. To transpile without bundling, use `Bun.Transpiler`. |
| `charset` | N/A | Not supported |
| `chunkNames` | `naming.chunk` | Uses the same template syntax as esbuild, but must explicitly include `[ext]`. |
| `color` | N/A | Bun returns log messages in the `logs` property of the build result. |
| `conditions` | N/A | Not supported. Export condition priority is determined by `target`. |
| `define` | `define` | |
| `drop` | N/A | Not supported |
| `entryNames` | `naming` or `naming.entry` | Bun supports a `naming` key that can be either a string or an object. Uses the same template syntax as esbuild, but must explicitly include `[ext]`. |
| `entryPoints` | `entrypoints` | Casing difference |
| `external` | `external` | No difference |
| `footer` | N/A | Not supported |
| `format` | `format` | Currently only supports `"esm"`. Plans to support `"cjs"` and `"iife"`. |
| `globalName` | N/A | Not supported |
| `ignoreAnnotations` | N/A | Not supported |
| `inject` | N/A | Not supported |
| `jsx` | `jsx` | Not supported in JS API; configure via `tsconfig.json` |
| `jsxDev` | `jsxDev` | Not supported in JS API; configure via `tsconfig.json` |
| `jsxFactory` | `jsxFactory` | Not supported in JS API; configure via `tsconfig.json` |
| `jsxFragment` | `jsxFragment` | Not supported in JS API; configure via `tsconfig.json` |
| `jsxImportSource` | `jsxImportSource` | Not supported in JS API; configure via `tsconfig.json` |
| `jsxSideEffects` | `jsxSideEffects` | Not supported in JS API; configure via `tsconfig.json` |
| `keepNames` | N/A | Not supported |
| `legalComments` | N/A | Not supported |
| `loader` | `loader` | Bun's set of built-in loaders differs from esbuild's; see Bundler > Loaders for complete reference. |
| `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` | `metafile` | Bun supports boolean, string (path), or object (with json/markdown paths) |
| `minify` | `minify` | In Bun, `minify` can be a boolean or object with granular control. |
| `minifyIdentifiers` | `minify.identifiers` | |
| `minifySyntax` | `minify.syntax` | |
| `minifyWhitespace` | `minify.whitespace` | |
| `nodePaths` | N/A | Not supported |
| `outExtension` | N/A | Not supported |
| `outbase` | `root` | |
| `outdir` | `outdir` | |
| `outfile` | `outfile` | |
| `packages` | `packages` | |
| `platform` | `target` | |
| `plugins` | `plugins` | Bun's plugin API is similar but not identical to esbuild's |
| `preserveSymlinks` | N/A | Not supported |
| `publicPath` | `publicPath` | |
| `pure` | N/A | Not supported |
| `resolveExtensions` | N/A | Not supported |
| `sourceRoot` | N/A | Not supported |
| `sourcemap` | `sourcemap` | No difference |
| `sourcesContent` | N/A | Not supported |
| `splitting` | `splitting` | |
| `stdin` | N/A | Not supported; Bun doesn't currently support stdin input |
| `supported` | N/A | Not supported |
| `target` | N/A | Not supported; Bun doesn't do syntax downleveling |
| `treeShaking` | N/A | Always enabled |
| `tsconfig` | `tsconfig` | |
| `write` | N/A | Always true when `outdir` is specified |
## Plugin API
Bun's plugin API is similar to esbuild's but not identical. Both use `onLoad` and `onResolve` hooks, but the exact API differs:
### esbuild
```ts theme={null}
const plugin = {
name: 'example',
setup(build) {
build.onResolve({ filter: /.*/ }, args => {
return { path: args.path };
});
build.onLoad({ filter: /.*/ }, args => {
return { contents: 'export default {}' };
});
}
};
```
### Bun
```ts theme={null}
const plugin: BunPlugin = {
name: 'example',
setup(build) {
build.onResolve({ filter: /.*/ }, args => {
return { path: args.path };
});
build.onLoad({ filter: /.*/ }, args => {
return { contents: 'export default {}', loader: 'js' };
});
}
};
```
Key differences:
* Bun requires explicit `loader` specification in `onLoad`
* Bun supports additional lifecycle hooks: `onStart`, `onEnd`, `onBeforeParse`
* Bun's plugin system is shared between runtime and bundler
See [Bundler > Plugins](/bundler/plugins) for complete documentation.
## Migration checklist
1. **Update your build script**
* Change `esbuild` to `bun build` in CLI commands
* Change `esbuild.build()` to `Bun.build()` in JavaScript
2. **Remove `--bundle` flag**
* Bun bundles by default
* Add `--no-bundle` if you need transpilation only
3. **Update loader syntax**
* Change `--loader:.svg=text` to `--loader .svg:text`
4. **Update naming options**
* `assetNames` → `naming.asset`
* `chunkNames` → `naming.chunk`
* `entryNames` → `naming.entry`
5. **Update platform option**
* `--platform` → `--target`
6. **Check unsupported features**
* Remove `--serve` (use `Bun.serve` instead)
* Remove `--target` (syntax downleveling not supported)
* Remove `--inject` if used
7. **Update plugins**
* Review plugin API differences
* Add explicit `loader` to `onLoad` returns
* Test plugin behavior
8. **Test your build**
* Run the new build command
* Verify output files
* Test in browsers/environments
## Example migration
### Before (esbuild)
```json package.json theme={null}
{
"scripts": {
"build": "esbuild src/index.ts --bundle --outdir=dist --minify --sourcemap"
}
}
```
### After (Bun)
```json package.json theme={null}
{
"scripts": {
"build": "bun build src/index.ts --outdir=dist --minify --sourcemap"
}
}
```
That's it! Most esbuild projects can be migrated with minimal changes.
## Getting help
If you encounter issues during migration:
1. Check the [Bun documentation](https://bun.sh/docs)
2. Search [GitHub issues](https://github.com/oven-sh/bun/issues)
3. Ask in the [Bun Discord](https://bun.sh/discord)
4. File a bug report if you find a problem