Bun esbuild

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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.

<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`.
</Note>

<Note>
  **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.
</Note>

## 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.

<Info>Bundling 10 copies of three.js from scratch, with sourcemaps and minification</Info>

## CLI API

Bun and esbuild both provide a command-line interface.

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# esbuild
esbuild <entrypoint> --outdir=out --bundle

# bun
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`.

| 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.<br />`esbuild --define:foo=bar`<br />`bun build --define foo=bar`                                                                                                                                                                                                                                                                    |
| `--external:<pkg>`     | `--external <pkg>`         | Small syntax difference; no colon.<br />`esbuild --external:react`<br />`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.<br /><br />The syntax for `--loader` is slightly different.<br />`esbuild app.ts --bundle --loader:.svg=text`<br />`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 <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`            |                                                                                                                                                                                                                                                                                                                                                                         |
| `--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`           | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                           |
| `--minify-whitespace`  | `--minify-whitespace`      |                                                                                                                                                                                                                                                                                                                                                                         |
| `--minify-identifiers` | `--minify-identifiers`     |                                                                                                                                                                                                                                                                                                                                                                         |
| `--minify-syntax`      | `--minify-syntax`          |                                                                                                                                                                                                                                                                                                                                                                         |
| `--out-extension`      | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                           |
| `--outbase`            | `--root`                   |                                                                                                                                                                                                                                                                                                                                                                         |
| `--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.                                                                                                                                                                                                                                                                                                                          |

## 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 same templating syntax as esbuild, but `[ext]` must be included explicitly.<br /><br />`ts<br/>Bun.build({<br/>  entrypoints: ["./index.tsx"],<br/>  naming: {<br/>    asset: "[name].[ext]",<br/>  },<br/>});<br/>`                                                                                                                                                                                                                                                                |
| `banner`            | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `bundle`            | n/a                        | Always true. Use `Bun.Transpiler` to transpile without bundling.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `charset`           | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

From jarle/bun-skills, MIT.

More from jarle/bun-skills