bun-types 1.3.2-canary.20251104T140728 → 1.3.2-canary.20251106T140813

package/docs/bundler/vs-esbuild.md

@@ -1,1127 +0,0 @@
-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`](https://bun.com/docs/api/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](https://github.com/oven-sh/bun/tree/main/bench/bundle).
-
-{% image src="/images/bundler-speed.png" caption="Bundling 10 copies of three.js from scratch, with sourcemaps and minification" /%}
-
-## 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
-- Bun always bundles, use `--no-bundle` to disable this behavior.
-
----
-
-- `--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 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](https://bun.com/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`
-- `--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`
-
----
-
-- `--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`. 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`
-- `--jsx-side-effects`
-- Controls whether JSX expressions are marked as `/* @__PURE__ */` for dead code elimination. Default is `false` (JSX marked as pure).
-
----
-
-- `--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.
-
-{% /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 `false`
-
----
-
-- `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`. Use [`Bun.Transpiler`](https://bun.com/docs/api/transpiler) to transpile without bundling.
-
----
-
-- `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`
-
----
-
-- `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`
-- Controls whether JSX expressions are marked as pure for dead code elimination
-
----
-
-- `keepNames`
-- n/a
-- Not supported
-
----
-
-- `legalComments`
-- n/a
-- Not supported
-
----
-
-- `loader`
-- `loader`
-- Bun supports a different set of built-in loaders than esbuild; see [Bundler > Loaders](https://bun.com/docs/bundler/loaders) for a complete reference. The esbuild loaders `dataurl`, `binary`, `base64`, `copy`, and `empty` are not yet implemented.
-
----
-
-- `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`
-- n/a
-- Not supported
-
-<!-- - `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
-  await 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). Does not support `"neutral"`.
-
----
-
-- `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`, and `resolve` utilities. `initialOptions` is partially implemented, being read-only and only having a subset of esbuild's options; use [`config`](https://bun.com/docs/bundler/plugins) (same thing but with Bun's `BuildConfig` format) instead.
-
-```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 %}