Buns Bundler-API ist stark von esbuild inspiriert. Die Migration von esbuild zu Buns Bundler sollte relativ schmerzlos sein. Dieser Leitfaden erklärt kurz, warum Sie eine Migration zu Buns Bundler in Betracht ziehen könnten, und bietet einen API-Vergleich für diejenigen, die bereits mit der esbuild-API vertraut sind.

Es gibt einige Verhaltensunterschiede zu beachten.

NOTE

**Standardmäßiges Bündeln.** Im Gegensatz zu esbuild bündelt Bun standardmäßig immer. Deshalb ist die `--bundle`-Flagge im Bun-Beispiel nicht erforderlich. Um jede Datei einzeln zu transpilieren, verwenden Sie `Bun.Transpiler`.

NOTE

**Es ist nur ein Bundler.** Im Gegensatz zu esbuild enthält Buns Bundler keinen integrierten Entwicklungsserver oder Datei-Watcher. Es ist nur ein Bundler. Der Bundler ist für die Verwendung in Verbindung mit `Bun.serve` und anderen Runtime-APIs vorgesehen, um den gleichen Effekt zu erzielen. Daher sind alle Optionen im Zusammenhang mit HTTP/Datei-Überwachung nicht anwendbar.

Leistung

Mit einer leistungsorientierten API, gekoppelt mit dem umfassend optimierten Zig-basierten JS/TS-Parser, ist Buns Bundler 1,75x schneller als esbuild im esbuild three.js-Benchmark.

CLI-API

Sowohl Bun als auch esbuild bieten eine Befehlszeilenschnittstelle.

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

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

In Buns CLI akzeptieren einfache boolesche Flags wie --minify kein Argument. Andere Flags wie --outdir <path> akzeptieren ein Argument; diese Flags können als --outdir out oder --outdir=out geschrieben werden. Einige Flags wie --define können mehrmals angegeben werden: --define foo=bar --define bar=baz.

esbuild	bun build	Hinweise
--bundle	n/a	Bun bündelt immer, verwenden Sie --no-bundle, um dieses Verhalten zu deaktivieren.
--define:K=V	--define K=V	Kleiner Syntaxunterschied; kein Doppelpunkt. esbuild --define:foo=bar bun build --define foo=bar
--external:<pkg>	--external <pkg>	Kleiner Syntaxunterschied; kein Doppelpunkt. esbuild --external:react bun build --external react
--format	--format	Bun unterstützt derzeit "esm" und "cjs", aber weitere Modulformate sind geplant. esbuild standardmäßig auf "iife".
--loader:.ext=loader	--loader .ext:loader	Bun unterstützt einen anderen Satz eingebauter Loader als esbuild; siehe Bundler > Loader für eine vollständige Referenz. Die esbuild-Loader dataurl, binary, base64, copy und empty sind noch nicht implementiert. Die Syntax für --loader ist leicht unterschiedlich. esbuild app.ts --bundle --loader:.svg=text bun build app.ts --loader .svg:text
--minify	--minify	Keine Unterschiede
--outdir	--outdir	Keine Unterschiede
--outfile	--outfile	Keine Unterschiede
--packages	--packages	Keine Unterschiede
--platform	--target	Umbenannt in --target für Konsistenz mit tsconfig. Unterstützt neutral nicht.
--serve	n/a	Nicht anwendbar
--sourcemap	--sourcemap	Keine Unterschiede
--splitting	--splitting	Keine Unterschiede
--target	n/a	Nicht unterstützt. Buns Bundler führt zu diesem Zeitpunkt kein syntaktisches Down-Leveling durch.
--watch	--watch	Keine Unterschiede
--allow-overwrite	n/a	Überschreiben ist nie erlaubt
--analyze	n/a	Nicht unterstützt
--asset-names	--asset-naming	Umbenannt für Konsistenz mit der Benennung in der JS-API
--banner	--banner	Gilt nur für JS-Bundles
--footer	--footer	Gilt nur für JS-Bundles
--certfile	n/a	Nicht anwendbar
--charset=utf8	n/a	Nicht unterstützt
--chunk-names	--chunk-naming	Umbenannt für Konsistenz mit der Benennung in der JS-API
--color	n/a	Immer aktiviert
--drop	--drop
--entry-names	--entry-naming	Umbenannt für Konsistenz mit der Benennung in der JS-API
--global-name	n/a	Nicht anwendbar, Bun unterstützt derzeit keine iife-Ausgabe
--ignore-annotations	--ignore-dce-annotations
--inject	n/a	Nicht unterstützt
--jsx	--jsx-runtime <runtime>	Unterstützt "automatic" (verwendet JSX-Transform) und "classic" (verwendet React.createElement)
--jsx-dev	n/a	Bun liest compilerOptions.jsx aus tsconfig.json, um einen Standardwert zu bestimmen. Wenn compilerOptions.jsx "react-jsx" ist oder wenn NODE_ENV=production, verwendet Bun die JSX-Transform. Andernfalls verwendet es jsxDEV. Der Bundler unterstützt preserve nicht.
--jsx-factory	--jsx-factory
--jsx-fragment	--jsx-fragment
--jsx-import-source	--jsx-import-source
--jsx-side-effects	n/a	JSX wird immer als nebenwirkungsfrei angenommen
--keep-names	n/a	Nicht unterstützt
--keyfile	n/a	Nicht anwendbar
--legal-comments	n/a	Nicht unterstützt
--log-level	n/a	Nicht unterstützt. Dies kann in bunfig.toml als logLevel festgelegt werden.
--log-limit	n/a	Nicht unterstützt
--log-override:X=Y	n/a	Nicht unterstützt
--main-fields	n/a	Nicht unterstützt
--mangle-cache	n/a	Nicht unterstützt
--mangle-props	n/a	Nicht unterstützt
--mangle-quoted	n/a	Nicht unterstützt
--metafile	n/a	Nicht unterstützt
--minify-whitespace	--minify-whitespace
--minify-identifiers	--minify-identifiers
--minify-syntax	--minify-syntax
--out-extension	n/a	Nicht unterstützt
--outbase	--root
--preserve-symlinks	n/a	Nicht unterstützt
--public-path	--public-path
--pure	n/a	Nicht unterstützt
--reserve-props	n/a	Nicht unterstützt
--resolve-extensions	n/a	Nicht unterstützt
--servedir	n/a	Nicht anwendbar
--source-root	n/a	Nicht unterstützt
--sourcefile	n/a	Nicht unterstützt. Bun unterstützt noch keine stdin-Eingabe.
--sourcemap	--sourcemap	Keine Unterschiede
--sources-content	n/a	Nicht unterstützt
--supported	n/a	Nicht unterstützt
--tree-shaking	n/a	Immer wahr
--tsconfig	--tsconfig-override
--version	n/a	Führen Sie bun --version aus, um die Version von Bun zu sehen.

JavaScript-API

esbuild.build()	Bun.build()	Hinweise
absWorkingDir	n/a	Immer auf process.cwd() gesetzt
alias	n/a	Nicht unterstützt
allowOverwrite	n/a	Immer falsch
assetNames	naming.asset	Verwendet die gleiche Templating-Syntax wie esbuild, aber [ext] muss explizit enthalten sein. ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> naming: {<br/> asset: "[name].[ext]",<br/> },<br/>});<br/>
banner	n/a	Nicht unterstützt
bundle	n/a	Immer wahr. Verwenden Sie Bun.Transpiler, um ohne Bündelung zu transpilieren.
charset	n/a	Nicht unterstützt
chunkNames	naming.chunk	Verwendet die gleiche Templating-Syntax wie esbuild, aber [ext] muss explizit enthalten sein. ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> naming: {<br/> chunk: "[name].[ext]",<br/> },<br/>});<br/>
color	n/a	Bun gibt Logs in der logs-Eigenschaft des Build-Ergebnisses zurück.
conditions	n/a	Nicht unterstützt. Die Priorität der Export-Bedingungen wird durch target bestimmt.
define	define
drop	n/a	Nicht unterstützt
entryNames	naming oder naming.entry	Bun unterstützt einen naming-Schlüssel, der entweder ein String oder ein Objekt sein kann. Verwendet die gleiche Templating-Syntax wie esbuild, aber [ext] muss explizit enthalten sein. ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> // wenn String, ist dies äquivalent zu entryNames<br/> naming: "[name].[ext]",<br/><br/> // granulare Benennungsoptionen<br/> naming: {<br/> entry: "[name].[ext]",<br/> asset: "[name].[ext]",<br/> chunk: "[name].[ext]",<br/> },<br/>});<br/>
entryPoints	entrypoints	Großschreibungsunterschied
external	external	Keine Unterschiede
footer	n/a	Nicht unterstützt
format	format	Unterstützt derzeit nur "esm". Unterstützung für "cjs" und "iife" ist geplant.
globalName	n/a	Nicht unterstützt
ignoreAnnotations	n/a	Nicht unterstützt
inject	n/a	Nicht unterstützt
jsx	jsx	Nicht in der JS-API unterstützt, in tsconfig.json konfigurieren
jsxDev	jsxDev	Nicht in der JS-API unterstützt, in tsconfig.json konfigurieren
jsxFactory	jsxFactory	Nicht in der JS-API unterstützt, in tsconfig.json konfigurieren
jsxFragment	jsxFragment	Nicht in der JS-API unterstützt, in tsconfig.json konfigurieren
jsxImportSource	jsxImportSource	Nicht in der JS-API unterstützt, in tsconfig.json konfigurieren
jsxSideEffects	jsxSideEffects	Nicht in der JS-API unterstützt, in tsconfig.json konfigurieren
keepNames	n/a	Nicht unterstützt
legalComments	n/a	Nicht unterstützt
loader	loader	Bun unterstützt einen anderen Satz eingebauter Loader als esbuild; siehe Bundler > Loader für eine vollständige Referenz. Die esbuild-Loader dataurl, binary, base64, copy und empty sind noch nicht implementiert.
logLevel	n/a	Nicht unterstützt
logLimit	n/a	Nicht unterstützt
logOverride	n/a	Nicht unterstützt
mainFields	n/a	Nicht unterstützt
mangleCache	n/a	Nicht unterstützt
mangleProps	n/a	Nicht unterstützt
mangleQuoted	n/a	Nicht unterstützt
metafile	n/a	Nicht unterstützt
minify	minify	In Bun kann minify ein boolescher Wert oder ein Objekt sein. ts<br/>await Bun.build({<br/> entrypoints: ['./index.tsx'],<br/> // alle Minifizierungen aktivieren<br/> minify: true<br/><br/> // granulare Optionen<br/> minify: {<br/> identifiers: true,<br/> syntax: true,<br/> whitespace: true<br/> }<br/>})<br/>
minifyIdentifiers	minify.identifiers	Siehe minify
minifySyntax	minify.syntax	Siehe minify
minifyWhitespace	minify.whitespace	Siehe minify
nodePaths	n/a	Nicht unterstützt
outExtension	n/a	Nicht unterstützt
outbase	root	Unterschiedlicher Name
outdir	outdir	Keine Unterschiede
outfile	outfile	Keine Unterschiede
packages	n/a	Nicht unterstützt, verwenden Sie external
platform	target	Unterstützt "bun", "node" und "browser" (der Standardwert). Unterstützt "neutral" nicht.
plugins	plugins	Buns Plugin-API ist eine Teilmenge von esbuilds. Einige esbuild-Plugins funktionieren sofort mit Bun.
preserveSymlinks	n/a	Nicht unterstützt
publicPath	publicPath	Keine Unterschiede
pure	n/a	Nicht unterstützt
reserveProps	n/a	Nicht unterstützt
resolveExtensions	n/a	Nicht unterstützt
sourceRoot	n/a	Nicht unterstützt
sourcemap	sourcemap	Unterstützt "inline", "external" und "none"
sourcesContent	n/a	Nicht unterstützt
splitting	splitting	Keine Unterschiede
stdin	n/a	Nicht unterstützt
supported	n/a	Nicht unterstützt
target	n/a	Keine Unterstützung für Syntax-Downleveling
treeShaking	n/a	Immer wahr
tsconfig	n/a	Nicht unterstützt
write	n/a	Auf wahr gesetzt, wenn outdir/outfile festgelegt ist, andernfalls falsch

Plugin-API

Buns Plugin-API ist darauf ausgelegt, mit esbuild kompatibel zu sein. Bun unterstützt nicht die gesamte Plugin-API-Oberfläche von esbuild, aber die Kernfunktionalität ist implementiert. Viele Drittanbieter-esbuild-Plugins funktionieren sofort mit Bun.

NOTE

Langfristig streben wir Funktionsparität mit der esbuild-API an. Wenn also etwas nicht funktioniert, erstellen Sie bitte ein Issue, um uns bei der Priorisierung zu helfen.

Plugins in Bun und esbuild werden mit einem Builder-Objekt definiert.

myPlugin.ts

import type { BunPlugin } from "bun";

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

Das Builder-Objekt bietet einige Methoden zum Ankoppeln an Teile des Bündelungsprozesses. Bun implementiert onResolve und onLoad; es implementiert noch nicht die esbuild-Hooks onStart, onEnd und onDispose sowie resolve-Utilities. initialOptions ist teilweise implementiert, schreibgeschützt und hat nur eine Teilmenge der esbuild-Optionen; verwenden Sie stattdessen config (dasselbe, aber mit Buns BuildConfig-Format).

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

Optionen

- 🟢 `filter`
- 🟢 `namespace`

Argumente

- 🟢 `path`
- 🟢 `importer`
- 🔴 `namespace`
- 🔴 `resolveDir`
- 🔴 `kind`
- 🔴 `pluginData`

Ergebnisse

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

onLoad

Optionen

- 🟢 `filter`
- 🟢 `namespace`

Argumente

- 🟢 `path`
- 🔴 `namespace`
- 🔴 `suffix`
- 🔴 `pluginData`

Ergebnisse

- 🟢 `contents`
- 🟢 `loader`
- 🔴 `errors`
- 🔴 `pluginData`
- 🔴 `pluginName`
- 🔴 `resolveDir`
- 🔴 `warnings`
- 🔴 `watchDirs`
- 🔴 `watchFiles`