L'API du bundler de Bun est fortement inspirée par esbuild. La migration vers le bundler de Bun depuis esbuild devrait être relativement indolore. Ce guide expliquera brièvement pourquoi vous pourriez envisager de migrer vers le bundler de Bun et fournira une référence API côte à côte pour ceux qui sont déjà familiers avec l'API d'esbuild.

Il y a quelques différences de comportement à noter.

NOTE

**Bundling par défaut.** Contrairement à esbuild, Bun effectue toujours le bundling par défaut. C'est pourquoi l'option `--bundle` n'est pas nécessaire dans l'exemple Bun. Pour transpiler chaque fichier individuellement, utilisez `Bun.Transpiler`.

NOTE

**C'est juste un bundler.** Contrairement à esbuild, le bundler de Bun n'inclut pas de serveur de développement intégré ni de surveilleur de fichiers. C'est juste un bundler. Le bundler est destiné à être utilisé en conjonction avec `Bun.serve` et d'autres API d'exécution pour obtenir le même effet. En tant que tel, toutes les options relatives au HTTP/surveillance de fichiers ne sont pas applicables.

Performance

Avec une API axée sur la performance couplée à l'analyseur JS/TS en Zig largement optimisé, le bundler de Bun est 1,75x plus rapide qu'esbuild sur le benchmark three.js d'esbuild.

API CLI

Bun et esbuild fournissent tous deux une interface de ligne de commande.

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

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

Dans la CLI de Bun, les options booléennes simples comme --minify n'acceptent pas d'argument. D'autres options comme --outdir <path> acceptent un argument ; ces options peuvent être écrites comme --outdir out ou --outdir=out. Certaines options comme --define peuvent être spécifiées plusieurs fois : --define foo=bar --define bar=baz.

esbuild	bun build	Notes
--bundle	n/a	Bun effectue toujours le bundling, utilisez --no-bundle pour désactiver ce comportement.
--define:K=V	--define K=V	Petite différence de syntaxe ; pas de deux-points. esbuild --define:foo=bar bun build --define foo=bar
--external:<pkg>	--external <pkg>	Petite différence de syntaxe ; pas de deux-points. esbuild --external:react bun build --external react
--format	--format	Bun prend en charge "esm" et "cjs" actuellement, mais plus de formats de modules sont prévus. esbuild utilise "iife" par défaut.
--loader:.ext=loader	--loader .ext:loader	Bun prend en charge un ensemble différent de chargeurs intégrés par rapport à esbuild ; consultez Bundler > Chargeurs pour une référence complète. Les chargeurs esbuild dataurl, binary, base64, copy, et empty ne sont pas encore implémentés. La syntaxe pour --loader est légèrement différente. esbuild app.ts --bundle --loader:.svg=text bun build app.ts --loader .svg:text
--minify	--minify	Aucune différence
--outdir	--outdir	Aucune différence
--outfile	--outfile	Aucune différence
--packages	--packages	Aucune différence
--platform	--target	Renommé en --target pour la cohérence avec tsconfig. Ne prend pas en charge neutral.
--serve	n/a	Non applicable
--sourcemap	--sourcemap	Aucune différence
--splitting	--splitting	Aucune différence
--target	n/a	Non pris en charge. Le bundler de Bun n'effectue aucun abaissement syntaxique pour le moment.
--watch	--watch	Aucune différence
--allow-overwrite	n/a	L'écrasement n'est jamais autorisé
--analyze	n/a	Non pris en charge
--asset-names	--asset-naming	Renommé pour la cohérence avec le nommage dans l'API JS
--banner	--banner	S'applique uniquement aux bundles js
--footer	--footer	S'applique uniquement aux bundles js
--certfile	n/a	Non applicable
--charset=utf8	n/a	Non pris en charge
--chunk-names	--chunk-naming	Renommé pour la cohérence avec le nommage dans l'API JS
--color	n/a	Toujours activé
--drop	--drop
--entry-names	--entry-naming	Renommé pour la cohérence avec le nommage dans l'API JS
--global-name	n/a	Non applicable, Bun ne prend pas en charge la sortie iife pour le moment
--ignore-annotations	--ignore-dce-annotations
--inject	n/a	Non pris en charge
--jsx	--jsx-runtime <runtime>	Prend en charge "automatic" (utilise la transformation jsx) et "classic" (utilise React.createElement)
--jsx-dev	n/a	Bun lit compilerOptions.jsx depuis tsconfig.json pour déterminer une valeur par défaut. Si compilerOptions.jsx est "react-jsx", ou si NODE_ENV=production, Bun utilisera la transformation jsx. Sinon, il utilise jsxDEV. Le bundler ne prend pas en charge preserve.
--jsx-factory	--jsx-factory
--jsx-fragment	--jsx-fragment
--jsx-import-source	--jsx-import-source
--jsx-side-effects	n/a	JSX est toujours considéré comme sans effet de bord
--keep-names	n/a	Non pris en charge
--keyfile	n/a	Non applicable
--legal-comments	n/a	Non pris en charge
--log-level	n/a	Non pris en charge. Cela peut être défini dans bunfig.toml comme logLevel.
--log-limit	n/a	Non pris en charge
--log-override:X=Y	n/a	Non pris en charge
--main-fields	n/a	Non pris en charge
--mangle-cache	n/a	Non pris en charge
--mangle-props	n/a	Non pris en charge
--mangle-quoted	n/a	Non pris en charge
--metafile	n/a	Non pris en charge
--minify-whitespace	--minify-whitespace
--minify-identifiers	--minify-identifiers
--minify-syntax	--minify-syntax
--out-extension	n/a	Non pris en charge
--outbase	--root
--preserve-symlinks	n/a	Non pris en charge
--public-path	--public-path
--pure	n/a	Non pris en charge
--reserve-props	n/a	Non pris en charge
--resolve-extensions	n/a	Non pris en charge
--servedir	n/a	Non applicable
--source-root	n/a	Non pris en charge
--sourcefile	n/a	Non pris en charge. Bun ne prend pas encore en charge l'entrée stdin.
--sourcemap	--sourcemap	Aucune différence
--sources-content	n/a	Non pris en charge
--supported	n/a	Non pris en charge
--tree-shaking	n/a	Toujours vrai
--tsconfig	--tsconfig-override
--version	n/a	Exécutez bun --version pour voir la version de Bun.

API JavaScript

esbuild.build()	Bun.build()	Notes
absWorkingDir	n/a	Toujours défini sur process.cwd()
alias	n/a	Non pris en charge
allowOverwrite	n/a	Toujours faux
assetNames	naming.asset	Utilise la même syntaxe de modèle qu'esbuild, mais [ext] doit être inclus explicitement. ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> naming: {<br/> asset: "[name].[ext]",<br/> },<br/>});<br/>
banner	n/a	Non pris en charge
bundle	n/a	Toujours vrai. Utilisez Bun.Transpiler pour transpiler sans bundling.
charset	n/a	Non pris en charge
chunkNames	naming.chunk	Utilise la même syntaxe de modèle qu'esbuild, mais [ext] doit être inclus explicitement. ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> naming: {<br/> chunk: "[name].[ext]",<br/> },<br/>});<br/>
color	n/a	Bun retourne les journaux dans la propriété logs du résultat de construction.
conditions	n/a	Non pris en charge. La priorité des conditions d'exportation est déterminée par target.
define	define
drop	n/a	Non pris en charge
entryNames	naming ou naming.entry	Bun prend en charge une clé naming qui peut être soit une chaîne soit un objet. Utilise la même syntaxe de modèle qu'esbuild, mais [ext] doit être inclus explicitement. ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> // quand chaîne, c'est équivalent à entryNames<br/> naming: "[name].[ext]",<br/><br/> // options de nommage granulaires<br/> naming: {<br/> entry: "[name].[ext]",<br/> asset: "[name].[ext]",<br/> chunk: "[name].[ext]",<br/> },<br/>});<br/>
entryPoints	entrypoints	Différence de capitalisation
external	external	Aucune différence
footer	n/a	Non pris en charge
format	format	Prend uniquement en charge "esm" actuellement. Le support pour "cjs" et "iife" est prévu.
globalName	n/a	Non pris en charge
ignoreAnnotations	n/a	Non pris en charge
inject	n/a	Non pris en charge
jsx	jsx	Non pris en charge dans l'API JS, configurez dans tsconfig.json
jsxDev	jsxDev	Non pris en charge dans l'API JS, configurez dans tsconfig.json
jsxFactory	jsxFactory	Non pris en charge dans l'API JS, configurez dans tsconfig.json
jsxFragment	jsxFragment	Non pris en charge dans l'API JS, configurez dans tsconfig.json
jsxImportSource	jsxImportSource	Non pris en charge dans l'API JS, configurez dans tsconfig.json
jsxSideEffects	jsxSideEffects	Non pris en charge dans l'API JS, configurez dans tsconfig.json
keepNames	n/a	Non pris en charge
legalComments	n/a	Non pris en charge
loader	loader	Bun prend en charge un ensemble différent de chargeurs intégrés par rapport à esbuild ; consultez Bundler > Chargeurs pour une référence complète. Les chargeurs esbuild dataurl, binary, base64, copy, et empty ne sont pas encore implémentés.
logLevel	n/a	Non pris en charge
logLimit	n/a	Non pris en charge
logOverride	n/a	Non pris en charge
mainFields	n/a	Non pris en charge
mangleCache	n/a	Non pris en charge
mangleProps	n/a	Non pris en charge
mangleQuoted	n/a	Non pris en charge
metafile	n/a	Non pris en charge
minify	minify	Dans Bun, minify peut être un booléen ou un objet. ts<br/>await Bun.build({<br/> entrypoints: ['./index.tsx'],<br/> // activer toute la minification<br/> minify: true<br/><br/> // options granulaires<br/> minify: {<br/> identifiers: true,<br/> syntax: true,<br/> whitespace: true<br/> }<br/>})<br/>
minifyIdentifiers	minify.identifiers	Voir minify
minifySyntax	minify.syntax	Voir minify
minifyWhitespace	minify.whitespace	Voir minify
nodePaths	n/a	Non pris en charge
outExtension	n/a	Non pris en charge
outbase	root	Nom différent
outdir	outdir	Aucune différence
outfile	outfile	Aucune différence
packages	n/a	Non pris en charge, utilisez external
platform	target	Prend en charge "bun", "node" et "browser" (la valeur par défaut). Ne prend pas en charge "neutral".
plugins	plugins	L'API de plugin de Bun est un sous-ensemble de celle d'esbuild. Certains plugins esbuild fonctionneront directement avec Bun.
preserveSymlinks	n/a	Non pris en charge
publicPath	publicPath	Aucune différence
pure	n/a	Non pris en charge
reserveProps	n/a	Non pris en charge
resolveExtensions	n/a	Non pris en charge
sourceRoot	n/a	Non pris en charge
sourcemap	sourcemap	Prend en charge "inline", "external", et "none"
sourcesContent	n/a	Non pris en charge
splitting	splitting	Aucune différence
stdin	n/a	Non pris en charge
supported	n/a	Non pris en charge
target	n/a	Aucun support pour l'abaissement de syntaxe
treeShaking	n/a	Toujours vrai
tsconfig	n/a	Non pris en charge
write	n/a	Défini sur vrai si outdir/outfile est défini, sinon faux

API de plugin

L'API de plugin de Bun est conçue pour être compatible avec esbuild. Bun ne prend pas en charge toute la surface de l'API de plugin d'esbuild, mais les fonctionnalités de base sont implémentées. De nombreux plugins esbuild tiers fonctionneront directement avec Bun.

NOTE

À long terme, nous visons la parité fonctionnelle avec l'API d'esbuild, donc si quelque chose ne fonctionne pas, veuillez ouvrir un problème pour nous aider à prioriser.

Les plugins dans Bun et esbuild sont définis avec un objet builder.

import type { BunPlugin } from "bun";

const myPlugin: BunPlugin = {
  name: "my-plugin",
  setup(builder) {
    // définir le plugin
  },
};

L'objet builder fournit des méthodes pour s'accrocher à différentes parties du processus de bundling. Bun implémente onResolve et onLoad ; il n'implémente pas encore les hooks esbuild onStart, onEnd, et onDispose, et les utilitaires resolve. initialOptions est partiellement implémenté, étant en lecture seule et n'ayant qu'un sous-ensemble des options d'esbuild ; utilisez config (la même chose mais avec le format BuildConfig de Bun) à la place.

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