L'API del bundler di Bun è fortemente ispirata da esbuild. Migrare al bundler di Bun da esbuild dovrebbe essere relativamente indolore. Questa guida spiegherà brevemente perché potresti considerare la migrazione al bundler di Bun e fornirà un riferimento di confronto API fianco a fianco per coloro che hanno già familiarità con l'API di esbuild.

Ci sono alcune differenze comportamentali da notare.

NOTE

**Bundling di default.** A differenza di esbuild, Bun esegue sempre il bundling di default. Questo è il motivo per cui il flag `--bundle` non è necessario nell'esempio Bun. Per transpilare ogni file individualmente, usa `Bun.Transpiler`.

NOTE

**È solo un bundler.** A differenza di esbuild, il bundler di Bun non include un development server integrato o un file watcher. È solo un bundler. Il bundler è inteso per essere usato in congiunzione con `Bun.serve` e altre API runtime per ottenere lo stesso effetto. Come tale, tutte le opzioni relative a HTTP/file watching non sono applicabili.

Prestazioni

Con un'API orientata alle prestazioni accoppiata con il parser JS/TS basato su Zig estesamente ottimizzato, il bundler di Bun è 1.75x più veloce di esbuild sul benchmark three.js di esbuild.

CLI API

Sia Bun che esbuild forniscono un'interfaccia a riga di comando.

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

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

Nella CLI di Bun, flag booleani semplici come --minify non accettano un argomento. Altri flag come --outdir <path> accettano un argomento; questi flag possono essere scritti come --outdir out o --outdir=out. Alcuni flag come --define possono essere specificati più volte: --define foo=bar --define bar=baz.

esbuild	bun build	Note
--bundle	n/a	Bun esegue sempre il bundling, usa --no-bundle per disabilitare questo comportamento.
--define:K=V	--define K=V	Piccola differenza di sintassi; nessun due punti. esbuild --define:foo=bar bun build --define foo=bar
--external:<pkg>	--external <pkg>	Piccola differenza di sintassi; nessun due punti. esbuild --external:react bun build --external react
--format	--format	Bun supporta "esm" e "cjs" attualmente, ma sono pianificati più formati di modulo. esbuild usa "iife" di default.
--loader:.ext=loader	--loader .ext:loader	Bun supporta un set diverso di loader built-in rispetto a esbuild; vedi Bundler > Loaders per un riferimento completo. I loader esbuild dataurl, binary, base64, copy, e empty non sono ancora implementati. La sintassi per --loader è leggermente diversa. esbuild app.ts --bundle --loader:.svg=text bun build app.ts --loader .svg:text
--minify	--minify	Nessuna differenza
--outdir	--outdir	Nessuna differenza
--outfile	--outfile	Nessuna differenza
--packages	--packages	Nessuna differenza
--platform	--target	Rinominato in --target per coerenza con tsconfig. Non supporta neutral.
--serve	n/a	Non applicabile
--sourcemap	--sourcemap	Nessuna differenza
--splitting	--splitting	Nessuna differenza
--target	n/a	Non supportato. Il bundler di Bun non esegue down-leveling sintattico al momento.
--watch	--watch	Nessuna differenza
--allow-overwrite	n/a	La sovrascrittura non è mai consentita
--analyze	n/a	Non supportato
--asset-names	--asset-naming	Rinominato per coerenza con il naming nella JS API
--banner	--banner	Si applica solo ai bundle js
--footer	--footer	Si applica solo ai bundle js
--certfile	n/a	Non applicabile
--charset=utf8	n/a	Non supportato
--chunk-names	--chunk-naming	Rinominato per coerenza con il naming nella JS API
--color	n/a	Sempre abilitato
--drop	--drop
--entry-names	--entry-naming	Rinominato per coerenza con il naming nella JS API
--global-name	n/a	Non applicabile, Bun non supporta output iife al momento
--ignore-annotations	--ignore-dce-annotations
--inject	n/a	Non supportato
--jsx	--jsx-runtime <runtime>	Supporta "automatic" (usa transform jsx) e "classic" (usa React.createElement)
--jsx-dev	n/a	Bun legge compilerOptions.jsx da tsconfig.json per determinare un default. Se compilerOptions.jsx è "react-jsx", o se NODE_ENV=production, Bun userà il transform jsx. Altrimenti, usa jsxDEV. Il bundler non supporta preserve.
--jsx-factory	--jsx-factory
--jsx-fragment	--jsx-fragment
--jsx-import-source	--jsx-import-source
--jsx-side-effects	n/a	JSX è sempre assunto come privo di effetti collaterali
--keep-names	n/a	Non supportato
--keyfile	n/a	Non applicabile
--legal-comments	n/a	Non supportato
--log-level	n/a	Non supportato. Questo può essere impostato in bunfig.toml come logLevel.
--log-limit	n/a	Non supportato
--log-override:X=Y	n/a	Non supportato
--main-fields	n/a	Non supportato
--mangle-cache	n/a	Non supportato
--mangle-props	n/a	Non supportato
--mangle-quoted	n/a	Non supportato
--metafile	n/a	Non supportato
--minify-whitespace	--minify-whitespace
--minify-identifiers	--minify-identifiers
--minify-syntax	--minify-syntax
--out-extension	n/a	Non supportato
--outbase	--root
--preserve-symlinks	n/a	Non supportato
--public-path	--public-path
--pure	n/a	Non supportato
--reserve-props	n/a	Non supportato
--resolve-extensions	n/a	Non supportato
--servedir	n/a	Non applicabile
--source-root	n/a	Non supportato
--sourcefile	n/a	Non supportato. Bun non supporta ancora input stdin.
--sourcemap	--sourcemap	Nessuna differenza
--sources-content	n/a	Non supportato
--supported	n/a	Non supportato
--tree-shaking	n/a	Sempre true
--tsconfig	--tsconfig-override
--version	n/a	Esegui bun --version per vedere la versione di Bun.

JavaScript API

esbuild.build()	Bun.build()	Note
absWorkingDir	n/a	Sempre impostato su process.cwd()
alias	n/a	Non supportato
allowOverwrite	n/a	Sempre false
assetNames	naming.asset	Usa la stessa sintassi di templating di esbuild, ma [ext] deve essere incluso esplicitamente. ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> naming: {<br/> asset: "[name].[ext]",<br/> },<br/>});<br/>
banner	n/a	Non supportato
bundle	n/a	Sempre true. Usa Bun.Transpiler per transpilare senza bundling.
charset	n/a	Non supportato
chunkNames	naming.chunk	Usa la stessa sintassi di templating di esbuild, ma [ext] deve essere incluso esplicitamente. ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> naming: {<br/> chunk: "[name].[ext]",<br/> },<br/>});<br/>
color	n/a	Bun restituisce i log nella proprietà logs del risultato della build.
conditions	n/a	Non supportato. La priorità delle condizioni di export è determinata da target.
define	define
drop	n/a	Non supportato
entryNames	naming o naming.entry	Bun supporta una chiave naming che può essere una stringa o un oggetto. Usa la stessa sintassi di templating di esbuild, ma [ext] deve essere inclusa esplicitamente. ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> // quando stringa, questo è equivalente a entryNames<br/> naming: "[name].[ext]",<br/><br/> // opzioni naming granulari<br/> naming: {<br/> entry: "[name].[ext]",<br/> asset: "[name].[ext]",<br/> chunk: "[name].[ext]",<br/> },<br/>});<br/>
entryPoints	entrypoints	Differenza di capitalizzazione
external	external	Nessuna differenza
footer	n/a	Non supportato
format	format	Supporta solo "esm" attualmente. Il supporto per "cjs" e "iife" è pianificato.
globalName	n/a	Non supportato
ignoreAnnotations	n/a	Non supportato
inject	n/a	Non supportato
jsx	jsx	Non supportato nella JS API, configura in tsconfig.json
jsxDev	jsxDev	Non supportato nella JS API, configura in tsconfig.json
jsxFactory	jsxFactory	Non supportato nella JS API, configura in tsconfig.json
jsxFragment	jsxFragment	Non supportato nella JS API, configura in tsconfig.json
jsxImportSource	jsxImportSource	Non supportato nella JS API, configura in tsconfig.json
jsxSideEffects	jsxSideEffects	Non supportato nella JS API, configura in tsconfig.json
keepNames	n/a	Non supportato
legalComments	n/a	Non supportato
loader	loader	Bun supporta un set diverso di loader built-in rispetto a esbuild; vedi Bundler > Loaders per un riferimento completo. I loader esbuild dataurl, binary, base64, copy, e empty non sono ancora implementati.
logLevel	n/a	Non supportato
logLimit	n/a	Non supportato
logOverride	n/a	Non supportato
mainFields	n/a	Non supportato
mangleCache	n/a	Non supportato
mangleProps	n/a	Non supportato
mangleQuoted	n/a	Non supportato
metafile	n/a	Non supportato
minify	minify	In Bun, minify può essere un booleano o un oggetto. ts<br/>await Bun.build({<br/> entrypoints: ['./index.tsx'],<br/> // abilita tutta la minificazione<br/> minify: true<br/><br/> // opzioni granulari<br/> minify: {<br/> identifiers: true,<br/> syntax: true,<br/> whitespace: true<br/> }<br/>})<br/>
minifyIdentifiers	minify.identifiers	Vedi minify
minifySyntax	minify.syntax	Vedi minify
minifyWhitespace	minify.whitespace	Vedi minify
nodePaths	n/a	Non supportato
outExtension	n/a	Non supportato
outbase	root	Nome diverso
outdir	outdir	Nessuna differenza
outfile	outfile	Nessuna differenza
packages	n/a	Non supportato, usa external
platform	target	Supporta "bun", "node" e "browser" (il default). Non supporta "neutral".
plugins	plugins	L'API plugin di Bun è un sottoinsieme di quella di esbuild. Alcuni plugin esbuild funzioneranno out of the box con Bun.
preserveSymlinks	n/a	Non supportato
publicPath	publicPath	Nessuna differenza
pure	n/a	Non supportato
reserveProps	n/a	Non supportato
resolveExtensions	n/a	Non supportato
sourceRoot	n/a	Non supportato
sourcemap	sourcemap	Supporta "inline", "external", e "none"
sourcesContent	n/a	Non supportato
splitting	splitting	Nessuna differenza
stdin	n/a	Non supportato
supported	n/a	Non supportato
target	n/a	Nessun supporto per downleveling sintattico
treeShaking	n/a	Sempre true
tsconfig	n/a	Non supportato
write	n/a	Impostato su true se outdir/outfile è impostato, altrimenti false

Plugin API

L'API plugin di Bun è progettata per essere compatibile con esbuild. Bun non supporta l'intera superficie API plugin di esbuild, ma la funzionalità core è implementata. Molti plugin esbuild di terze parti funzioneranno out of the box con Bun.

NOTE

A lungo termine, miriamo alla parità di funzionalità con l'API di esbuild, quindi se qualcosa non funziona per favore apri una issue per aiutarci a dare priorità.

I plugin in Bun e esbuild sono definiti con un oggetto builder.

myPlugin.ts

import type { BunPlugin } from "bun";

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

L'oggetto builder fornisce alcuni metodi per agganciarsi a parti del processo di bundling. Bun implementa onResolve e onLoad; non implementa ancora gli hook esbuild onStart, onEnd, e onDispose, e le utility resolve. initialOptions è parzialmente implementato, essendo read-only e avendo solo un sottoinsieme delle opzioni di esbuild; usa config (la stessa cosa ma con il formato BuildConfig di Bun) invece.

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