La API del empaquetador de Bun está fuertemente inspirada en esbuild. Migrar al empaquetador de Bun desde esbuild debería ser relativamente indoloro. Esta guía explicará brevemente por qué podrías considerar migrar al empaquetador de Bun y proporcionará una referencia de comparación de API lado a lado para aquellos que ya están familiarizados con la API de esbuild.

Hay algunas diferencias de comportamiento a tener en cuenta.

NOTE

**Empaquetado por defecto.** A diferencia de esbuild, Bun siempre empaqueta por defecto. Esta es la razón por la que la bandera `--bundle` no es necesaria en el ejemplo de Bun. Para transpilar cada archivo individualmente, usa `Bun.Transpiler`.

NOTE

**Es solo un empaquetador.** A diferencia de esbuild, el empaquetador de Bun no incluye un servidor de desarrollo integrado o vigilante de archivos. Es solo un empaquetador. El empaquetador está destinado a usarse en conjunto con `Bun.serve` y otras APIs de runtime para lograr el mismo efecto. Como tal, todas las opciones relacionadas con HTTP/vigilancia de archivos no son aplicables.

Rendimiento

Con una API orientada al rendimiento acoplada con el parser JS/TS basado en Zig extensamente optimizado, el empaquetador de Bun es 1.75x más rápido que esbuild en el benchmark three.js de esbuild.

API de CLI

Tanto Bun como esbuild proporcionan una interfaz de línea de comandos.

# esbuild
esbuild <entrypoint> --outdir=out --bundle

# bun
bun build <entrypoint> --outdir=out

En el CLI de Bun, banderas booleanas simples como --minify no aceptan un argumento. Otras banderas como --outdir <path> sí aceptan un argumento; estas banderas pueden escribirse como --outdir out o --outdir=out. Algunas banderas como --define pueden especificarse varias veces: --define foo=bar --define bar=baz.

esbuild	bun build	Notas
--bundle	n/a	Bun siempre empaqueta, usa --no-bundle para deshabilitar este comportamiento.
--define:K=V	--define K=V	Pequeña diferencia de sintaxis; sin dos puntos. esbuild --define:foo=bar bun build --define foo=bar
--external:<pkg>	--external <pkg>	Pequeña diferencia de sintaxis; sin dos puntos. esbuild --external:react bun build --external react
--format	--format	Bun soporta "esm" y "cjs" actualmente, pero hay más formatos de módulo planificados. esbuild usa "iife" por defecto.
--loader:.ext=loader	--loader .ext:loader	Bun soporta un conjunto diferente de loaders integrados que esbuild; consulta Bundler > Loaders para una referencia completa. Los loaders de esbuild dataurl, binary, base64, copy, y empty aún no están implementados. La sintaxis para --loader es ligeramente diferente. esbuild app.ts --bundle --loader:.svg=text bun build app.ts --loader .svg:text
--minify	--minify	Sin diferencias
--outdir	--outdir	Sin diferencias
--outfile	--outfile	Sin diferencias
--packages	--packages	Sin diferencias
--platform	--target	Renombrado a --target para consistencia con tsconfig. No soporta neutral.
--serve	n/a	No aplicable
--sourcemap	--sourcemap	Sin diferencias
--splitting	--splitting	Sin diferencias
--target	n/a	No soportado. El empaquetador de Bun no realiza down-leveling sintáctico en este momento.
--watch	--watch	Sin diferencias
--allow-overwrite	n/a	Sobrescribir nunca está permitido
--analyze	n/a	No soportado
--asset-names	--asset-naming	Renombrado para consistencia con naming en la API de JS
--banner	--banner	Solo aplica a bundles js
--footer	--footer	Solo aplica a bundles js
--certfile	n/a	No aplicable
--charset=utf8	n/a	No soportado
--chunk-names	--chunk-naming	Renombrado para consistencia con naming en la API de JS
--color	n/a	Siempre habilitado
--drop	--drop
--entry-names	--entry-naming	Renombrado para consistencia con naming en la API de JS
--global-name	n/a	No aplicable, Bun no soporta salida iife en este momento
--ignore-annotations	--ignore-dce-annotations
--inject	n/a	No soportado
--jsx	--jsx-runtime <runtime>	Soporta "automatic" (usa transformación jsx) y "classic" (usa React.createElement)
--jsx-dev	n/a	Bun lee compilerOptions.jsx de tsconfig.json para determinar un valor por defecto. Si compilerOptions.jsx es "react-jsx", o si NODE_ENV=production, Bun usará la transformación jsx. De lo contrario, usa jsxDEV. El empaquetador no soporta preserve.
--jsx-factory	--jsx-factory
--jsx-fragment	--jsx-fragment
--jsx-import-source	--jsx-import-source
--jsx-side-effects	n/a	JSX siempre se asume libre de efectos secundarios
--keep-names	n/a	No soportado
--keyfile	n/a	No aplicable
--legal-comments	n/a	No soportado
--log-level	n/a	No soportado. Esto puede establecerse en bunfig.toml como logLevel.
--log-limit	n/a	No soportado
--log-override:X=Y	n/a	No soportado
--main-fields	n/a	No soportado
--mangle-cache	n/a	No soportado
--mangle-props	n/a	No soportado
--mangle-quoted	n/a	No soportado
--metafile	n/a	No soportado
--minify-whitespace	--minify-whitespace
--minify-identifiers	--minify-identifiers
--minify-syntax	--minify-syntax
--out-extension	n/a	No soportado
--outbase	--root
--preserve-symlinks	n/a	No soportado
--public-path	--public-path
--pure	n/a	No soportado
--reserve-props	n/a	No soportado
--resolve-extensions	n/a	No soportado
--servedir	n/a	No aplicable
--source-root	n/a	No soportado
--sourcefile	n/a	No soportado. Bun aún no soporta entrada stdin.
--sourcemap	--sourcemap	Sin diferencias
--sources-content	n/a	No soportado
--supported	n/a	No soportado
--tree-shaking	n/a	Siempre verdadero
--tsconfig	--tsconfig-override
--version	n/a	Ejecuta bun --version para ver la versión de Bun.

API de JavaScript

esbuild.build()	Bun.build()	Notas
absWorkingDir	n/a	Siempre establecido a process.cwd()
alias	n/a	No soportado
allowOverwrite	n/a	Siempre falso
assetNames	naming.asset	Usa la misma sintaxis de plantillas que esbuild, pero [ext] debe incluirse explícitamente. ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> naming: {<br/> asset: "[name].[ext]",<br/> },<br/>});<br/>
banner	n/a	No soportado
bundle	n/a	Siempre verdadero. Usa Bun.Transpiler para transpilar sin empaquetar.
charset	n/a	No soportado
chunkNames	naming.chunk	Usa la misma sintaxis de plantillas que esbuild, pero [ext] debe incluirse explícitamente. ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> naming: {<br/> chunk: "[name].[ext]",<br/> },<br/>});<br/>
color	n/a	Bun devuelve logs en la propiedad logs del resultado de construcción.
conditions	n/a	No soportado. La prioridad de condiciones de exportación está determinada por target.
define	define
drop	n/a	No soportado
entryNames	naming o naming.entry	Bun soporta una clave naming que puede ser una cadena o un objeto. Usa la misma sintaxis de plantillas que esbuild, pero [ext] debe incluirse explícitamente. ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> // cuando es cadena, esto es equivalente a entryNames<br/> naming: "[name].[ext]",<br/><br/> // opciones de naming granulares<br/> naming: {<br/> entry: "[name].[ext]",<br/> asset: "[name].[ext]",<br/> chunk: "[name].[ext]",<br/> },<br/>});<br/>
entryPoints	entrypoints	Diferencia de capitalización
external	external	Sin diferencias
footer	n/a	No soportado
format	format	Solo soporta "esm" actualmente. El soporte para "cjs" e "iife" está planificado.
globalName	n/a	No soportado
ignoreAnnotations	n/a	No soportado
inject	n/a	No soportado
jsx	jsx	No soportado en la API de JS, configura en tsconfig.json
jsxDev	jsxDev	No soportado en la API de JS, configura en tsconfig.json
jsxFactory	jsxFactory	No soportado en la API de JS, configura en tsconfig.json
jsxFragment	jsxFragment	No soportado en la API de JS, configura en tsconfig.json
jsxImportSource	jsxImportSource	No soportado en la API de JS, configura en tsconfig.json
jsxSideEffects	jsxSideEffects	No soportado en la API de JS, configura en tsconfig.json
keepNames	n/a	No soportado
legalComments	n/a	No soportado
loader	loader	Bun soporta un conjunto diferente de loaders integrados que esbuild; consulta Bundler > Loaders para una referencia completa. Los loaders de esbuild dataurl, binary, base64, copy, y empty aún no están implementados.
logLevel	n/a	No soportado
logLimit	n/a	No soportado
logOverride	n/a	No soportado
mainFields	n/a	No soportado
mangleCache	n/a	No soportado
mangleProps	n/a	No soportado
mangleQuoted	n/a	No soportado
metafile	n/a	No soportado
minify	minify	En Bun, minify puede ser un booleano o un objeto. ts<br/>await Bun.build({<br/> entrypoints: ['./index.tsx'],<br/> // habilitar toda la minificación<br/> minify: true<br/><br/> // opciones granulares<br/> minify: {<br/> identifiers: true,<br/> syntax: true,<br/> whitespace: true<br/> }<br/>})<br/>
minifyIdentifiers	minify.identifiers	Ver minify
minifySyntax	minify.syntax	Ver minify
minifyWhitespace	minify.whitespace	Ver minify
nodePaths	n/a	No soportado
outExtension	n/a	No soportado
outbase	root	Nombre diferente
outdir	outdir	Sin diferencias
outfile	outfile	Sin diferencias
packages	n/a	No soportado, usa external
platform	target	Soporta "bun", "node" y "browser" (el predeterminado). No soporta "neutral".
plugins	plugins	La API de plugins de Bun es un subconjunto de la de esbuild. Algunos plugins de esbuild funcionarán directamente con Bun.
preserveSymlinks	n/a	No soportado
publicPath	publicPath	Sin diferencias
pure	n/a	No soportado
reserveProps	n/a	No soportado
resolveExtensions	n/a	No soportado
sourceRoot	n/a	No soportado
sourcemap	sourcemap	Soporta "inline", "external", y "none"
sourcesContent	n/a	No soportado
splitting	splitting	Sin diferencias
stdin	n/a	No soportado
supported	n/a	No soportado
target	n/a	Sin soporte para downleveling de sintaxis
treeShaking	n/a	Siempre verdadero
tsconfig	n/a	No soportado
write	n/a	Establecido a verdadero si outdir/outfile está establecido, de lo contrario falso

API de Plugins

La API de plugins de Bun está diseñada para ser compatible con esbuild. Bun no soporta toda la superficie de la API de plugins de esbuild, pero la funcionalidad principal está implementada. Muchos plugins de terceros de esbuild funcionarán directamente con Bun.

NOTE

A largo plazo, apuntamos a paridad de características con la API de esbuild, así que si algo no funciona, por favor reporta un problema para ayudarnos a priorizar.

Los plugins en Bun y esbuild se definen con un objeto builder.

myPlugin.ts

import type { BunPlugin } from "bun";

const myPlugin: BunPlugin = {
  name: "my-plugin",
  setup(builder) {
    // definir plugin
  },
};

El objeto builder proporciona algunos métodos para conectarse a partes del proceso de empaquetado. Bun implementa onResolve y onLoad; aún no implementa los hooks de esbuild onStart, onEnd, y onDispose, y utilidades resolve. initialOptions está parcialmente implementado, siendo de solo lectura y teniendo solo un subconjunto de las opciones de esbuild; usa config (lo mismo pero con el formato BuildConfig de Bun) en su lugar.

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

• 🟢 filter
• 🟢 namespace

arguments

• 🟢 path
• 🟢 importer
• 🔴 namespace
• 🔴 resolveDir
• 🔴 kind
• 🔴 pluginData

results

• 🟢 namespace
• 🟢 path
• 🔴 errors
• 🔴 external
• 🔴 pluginData
• 🔴 pluginName
• 🔴 sideEffects
• 🔴 suffix
• 🔴 warnings
• 🔴 watchDirs
• 🔴 watchFiles

onLoad

options

• 🟢 filter
• 🟢 namespace

arguments

• 🟢 path
• 🔴 namespace
• 🔴 suffix
• 🔴 pluginData

results

• 🟢 contents
• 🟢 loader
• 🔴 errors
• 🔴 pluginData
• 🔴 pluginName
• 🔴 resolveDir
• 🔴 warnings
• 🔴 watchDirs
• 🔴 watchFiles