A API do bundler do Bun é fortemente inspirada pelo esbuild. Migrar para o bundler do Bun a partir do esbuild deve ser relativamente simples. Este guia explicará brevemente por que você pode considerar migrar para o bundler do Bun e fornecerá uma referência de API lado a lado para aqueles que já estão familiarizados com a API do esbuild.

Há algumas diferenças comportamentais a serem observadas.

NOTE

**Bundling por padrão.** Diferentemente do esbuild o Bun sempre faz bundling por padrão. É por isso que a flag `--bundle` não é necessária no exemplo do Bun. Para transpilar cada arquivo individualmente use `Bun.Transpiler`.

NOTE

**É apenas um bundler.** Diferentemente do esbuild o bundler do Bun não inclui um development server ou file watcher built-in. É apenas um bundler. O bundler é destinado a ser usado em conjunto com `Bun.serve` e outras APIs de runtime para alcançar o mesmo efeito. Como tal todas as opções relacionadas a HTTP/file watching não se aplicam.

Desempenho

Com uma API orientada a desempenho acoplada com o parser JS/TS baseado em Zig extensivamente otimizado o bundler do Bun é 1,75x mais rápido que o esbuild no benchmark three.js do esbuild.

CLI API

Tanto o Bun quanto o esbuild fornecem uma interface de linha de comando.

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

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

Na CLI do Bun flags booleanas simples como --minify não aceitam um argumento. Outras flags como --outdir <path> aceitam um argumento; estas flags podem ser escritas como --outdir out ou --outdir=out. Algumas flags como --define podem ser especificadas várias vezes: --define foo=bar --define bar=baz.

esbuild	bun build	Notas
--bundle	n/a	O Bun sempre faz bundling use --no-bundle para desabilitar este comportamento.
--define:K=V	--define K=V	Pequena diferença de sintaxe sem dois pontos. esbuild --define:foo=bar bun build --define foo=bar
--external:<pkg>	--external <pkg>	Pequena diferença de sintaxe sem dois pontos. esbuild --external:react bun build --external react
--format	--format	O Bun suporta "esm" e "cjs" atualmente mas mais formatos de módulo são planejados. esbuild usa como padrão "iife".
--loader:.ext=loader	--loader .ext:loader	O Bun suporta um conjunto diferente de loaders built-in que o esbuild; veja Bundler > Loaders para uma referência completa. Os loaders do esbuild dataurl, binary, base64, copy e empty ainda não estão implementados. A sintaxe para --loader é ligeiramente diferente. esbuild app.ts --bundle --loader:.svg=text bun build app.ts --loader .svg:text
--minify	--minify	Sem diferenças
--outdir	--outdir	Sem diferenças
--outfile	--outfile	Sem diferenças
--packages	--packages	Sem diferenças
--platform	--target	Renomeado para --target para consistência com tsconfig. Não suporta neutral.
--serve	n/a	Não se aplica
--sourcemap	--sourcemap	Sem diferenças
--splitting	--splitting	Sem diferenças
--target	n/a	Não suportado. O bundler do Bun não faz syntactic down-leveling neste momento.
--watch	--watch	Sem diferenças
--allow-overwrite	n/a	Overwriting nunca é permitido
--analyze	n/a	Não suportado
--asset-names	--asset-naming	Renomeado para consistência com naming na API JS
--banner	--banner	Apenas se aplica a bundles js
--footer	--footer	Apenas se aplica a bundles js
--certfile	n/a	Não se aplica
--charset=utf8	n/a	Não suportado
--chunk-names	--chunk-naming	Renomeado para consistência com naming na API JS
--color	n/a	Sempre habilitado
--drop	--drop
--entry-names	--entry-naming	Renomeado para consistência com naming na API JS
--global-name	n/a	Não se aplica o Bun não suporta output iife neste momento
--ignore-annotations	--ignore-dce-annotations
--inject	n/a	Não suportado
--jsx	--jsx-runtime <runtime>	Suporta "automatic" (usa jsx transform) e "classic" (usa React.createElement)
--jsx-dev	n/a	O Bun lê compilerOptions.jsx de tsconfig.json para determinar um padrão. Se compilerOptions.jsx for "react-jsx" ou se NODE_ENV=production o Bun usará o jsx transform. Caso contrário usa jsxDEV. O bundler não suporta preserve.
--jsx-factory	--jsx-factory
--jsx-fragment	--jsx-fragment
--jsx-import-source	--jsx-import-source
--jsx-side-effects	n/a	JSX é sempre assumido como side-effect-free
--keep-names	n/a	Não suportado
--keyfile	n/a	Não se aplica
--legal-comments	n/a	Não suportado
--log-level	n/a	Não suportado. Isso pode ser definido em bunfig.toml como logLevel.
--log-limit	n/a	Não suportado
--log-override:X=Y	n/a	Não suportado
--main-fields	n/a	Não suportado
--mangle-cache	n/a	Não suportado
--mangle-props	n/a	Não suportado
--mangle-quoted	n/a	Não suportado
--metafile	n/a	Não suportado
--minify-whitespace	--minify-whitespace
--minify-identifiers	--minify-identifiers
--minify-syntax	--minify-syntax
--out-extension	n/a	Não suportado
--outbase	--root
--preserve-symlinks	n/a	Não suportado
--public-path	--public-path
--pure	n/a	Não suportado
--reserve-props	n/a	Não suportado
--resolve-extensions	n/a	Não suportado
--servedir	n/a	Não se aplica
--source-root	n/a	Não suportado
--sourcefile	n/a	Não suportado. O Bun ainda não suporta entrada stdin.
--sourcemap	--sourcemap	Sem diferenças
--sources-content	n/a	Não suportado
--supported	n/a	Não suportado
--tree-shaking	n/a	Sempre true
--tsconfig	--tsconfig-override
--version	n/a	Execute bun --version para ver a versão do Bun.

JavaScript API

esbuild.build()	Bun.build()	Notas
absWorkingDir	n/a	Sempre definido como process.cwd()
alias	n/a	Não suportado
allowOverwrite	n/a	Sempre false
assetNames	naming.asset	Usa a mesma sintaxe de templating que o esbuild mas [ext] deve ser incluído explicitamente. ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> naming: {<br/> asset: "[name].[ext]",<br/> },<br/>});<br/>
banner	n/a	Não suportado
bundle	n/a	Sempre true. Use Bun.Transpiler para transpilar sem bundling.
charset	n/a	Não suportado
chunkNames	naming.chunk	Usa a mesma sintaxe de templating que o esbuild mas [ext] deve ser incluído explicitamente. ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> naming: {<br/> chunk: "[name].[ext]",<br/> },<br/>});<br/>
color	n/a	O Bun retorna logs na propriedade logs do resultado do build.
conditions	n/a	Não suportado. A prioridade de condições de export é determinada por target.
define	define
drop	n/a	Não suportado
entryNames	naming ou naming.entry	O Bun suporta uma chave naming que pode ser uma string ou um objeto. Usa a mesma sintaxe de templating que o esbuild mas [ext] deve ser incluído explicitamente. ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> // quando string isso é equivalente a entryNames<br/> naming: "[name].[ext]",<br/><br/> // opções granulares de naming<br/> naming: {<br/> entry: "[name].[ext]",<br/> asset: "[name].[ext]",<br/> chunk: "[name].[ext]",<br/> },<br/>});<br/>
entryPoints	entrypoints	Diferença de capitalização
external	external	Sem diferenças
footer	n/a	Não suportado
format	format	Apenas suporta "esm" atualmente. Suporte para "cjs" e "iife" é planejado.
globalName	n/a	Não suportado
ignoreAnnotations	n/a	Não suportado
inject	n/a	Não suportado
jsx	jsx	Não suportado na API JS configure em tsconfig.json
jsxDev	jsxDev	Não suportado na API JS configure em tsconfig.json
jsxFactory	jsxFactory	Não suportado na API JS configure em tsconfig.json
jsxFragment	jsxFragment	Não suportado na API JS configure em tsconfig.json
jsxImportSource	jsxImportSource	Não suportado na API JS configure em tsconfig.json
jsxSideEffects	jsxSideEffects	Não suportado na API JS configure em tsconfig.json
keepNames	n/a	Não suportado
legalComments	n/a	Não suportado
loader	loader	O Bun suporta um conjunto diferente de loaders built-in que o esbuild; veja Bundler > Loaders para uma referência completa. Os loaders do esbuild dataurl, binary, base64, copy e empty ainda não estão implementados.
logLevel	n/a	Não suportado
logLimit	n/a	Não suportado
logOverride	n/a	Não suportado
mainFields	n/a	Não suportado
mangleCache	n/a	Não suportado
mangleProps	n/a	Não suportado
mangleQuoted	n/a	Não suportado
metafile	n/a	Não suportado
minify	minify	No Bun minify pode ser um boolean ou um objeto. ts<br/>await Bun.build({<br/> entrypoints: ['./index.tsx'],<br/> // habilita toda minificação<br/> minify: true<br/><br/> // opções granulares<br/> minify: {<br/> identifiers: true,<br/> syntax: true,<br/> whitespace: true<br/> }<br/>})<br/>
minifyIdentifiers	minify.identifiers	Veja minify
minifySyntax	minify.syntax	Veja minify
minifyWhitespace	minify.whitespace	Veja minify
nodePaths	n/a	Não suportado
outExtension	n/a	Não suportado
outbase	root	Nome diferente
outdir	outdir	Sem diferenças
outfile	outfile	Sem diferenças
packages	n/a	Não suportado use external
platform	target	Suporta "bun", "node" e "browser" (o padrão). Não suporta "neutral".
plugins	plugins	A API de plugins do Bun é um subconjunto da API do esbuild. Alguns plugins do esbuild funcionarão imediatamente com o Bun.
preserveSymlinks	n/a	Não suportado
publicPath	publicPath	Sem diferenças
pure	n/a	Não suportado
reserveProps	n/a	Não suportado
resolveExtensions	n/a	Não suportado
sourceRoot	n/a	Não suportado
sourcemap	sourcemap	Suporta "inline", "external" e "none"
sourcesContent	n/a	Não suportado
splitting	splitting	Sem diferenças
stdin	n/a	Não suportado
supported	n/a	Não suportado
target	n/a	Sem suporte para syntax downleveling
treeShaking	n/a	Sempre true
tsconfig	n/a	Não suportado
write	n/a	Definido como true se outdir/outfile estiver definido caso contrário false

Plugin API

A API de plugins do Bun é projetada para ser compatível com o esbuild. O Bun não suporta toda a superfície da API de plugins do esbuild mas a funcionalidade principal é implementada. Muitos plugins de terceiros do esbuild funcionarão imediatamente com o Bun.

NOTE

Longo prazo visamos paridade de recursos com a API do esbuild então se algo não funcionar por favor abra uma issue para nos ajudar a priorizar.

Plugins no Bun e esbuild são definidos com um builder object.

myPlugin.ts

import type { BunPlugin } from "bun";

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

O builder object fornece alguns métodos para hooking em partes do processo de bundling. O Bun implementa onResolve e onLoad; ainda não implementa os hooks do esbuild onStart, onEnd e onDispose e utilitários resolve. initialOptions é parcialmente implementado sendo read-only e tendo apenas um subconjunto das opções do esbuild; use config (a mesma coisa mas com o formato BuildConfig do Bun) em vez disso.

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