API бандлера Bun в значительной степени вдохновлен esbuild. Миграция на бандлер Bun с esbuild должна быть относительно безболезненной. Это руководство кратко объяснит почему вы можете рассмотреть миграцию на бандлер Bun и предоставит справочник API для тех кто уже знаком с API esbuild.

Есть несколько поведенческих различий о которых следует отметить.

NOTE

**Связывание по умолчанию.** В отличие от esbuild Bun всегда связывает по умолчанию. Вот почему флаг `--bundle` не необходим в примере Bun. Для транспиляции каждого файла индивидуально используйте `Bun.Transpiler`.

NOTE

**Это просто бандлер.** В отличие от esbuild бандлер Bun не включает встроенный сервер разработки или наблюдатель файлов. Это просто бандлер. Бандлер предназначен для использования в сочетании с `Bun.serve` и другими API времени выполнения для достижения того же эффекта. Таким образом все опции связанные с HTTP/наблюдением за файлами не применимы.

Производительность

С API ориентированным на производительность в сочетании с чрезвычайно оптимизированным парсером JS/TS на Zig бандлер Bun в 1,75 раза быстрее esbuild на бенчмарке three.js от esbuild.

CLI API

И Bun и esbuild предоставляют интерфейс командной строки.

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

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

В CLI Bun простые булевы флаги такие как --minify не принимают аргумент. Другие флаги такие как --outdir <path> принимают аргумент; эти флаги могут быть записаны как --outdir out или --outdir=out. Некоторые флаги такие как --define могут быть указаны несколько раз: --define foo=bar --define bar=baz.

esbuild	bun build	Примечания
--bundle	н/д	Bun всегда связывает используйте --no-bundle для отключения этого поведения.
--define:K=V	--define K=V	Небольшое различие в синтаксисе; без двоеточия. esbuild --define:foo=bar bun build --define foo=bar
--external:<pkg>	--external <pkg>	Небольшое различие в синтаксисе; без двоеточия. esbuild --external:react bun build --external react
--format	--format	Bun поддерживает "esm" и "cjs" в настоящее время но планируется больше форматов модулей. esbuild по умолчанию использует "iife".
--loader:.ext=loader	--loader .ext:loader	Bun поддерживает другой набор встроенных загрузчиков чем esbuild; полный справочник смотрите на странице Bundler > Loaders. Загрузчики esbuild dataurl binary base64 copy и empty еще не реализованы. Синтаксис для --loader немного отличается. esbuild app.ts --bundle --loader:.svg=text bun build app.ts --loader .svg:text
--minify	--minify	Нет различий
--outdir	--outdir	Нет различий
--outfile	--outfile	Нет различий
--packages	--packages	Нет различий
--platform	--target	Переименовано в --target для согласованности с tsconfig. Не поддерживает neutral.
--serve	н/д	Не применимо
--sourcemap	--sourcemap	Нет различий
--splitting	--splitting	Нет различий
--target	н/д	Не поддерживается. Бандлер Bun в настоящее время не выполняет синтаксическое понижение.
--watch	--watch	Нет различий
--allow-overwrite	н/д	Перезапись никогда не разрешается
--analyze	н/д	Не поддерживается
--asset-names	--asset-naming	Переименовано для согласованности с naming в JS API
--banner	--banner	Применяется только к js бандлам
--footer	--footer	Применяется только к js бандлам
--certfile	н/д	Не применимо
--charset=utf8	н/д	Не поддерживается
--chunk-names	--chunk-naming	Переименовано для согласованности с naming в JS API
--color	н/д	Всегда включено
--drop	--drop
--entry-names	--entry-naming	Переименовано для согласованности с naming в JS API
--global-name	н/д	Не применимо Bun в настоящее время не поддерживает вывод iife
--ignore-annotations	--ignore-dce-annotations
--inject	н/д	Не поддерживается
--jsx	--jsx-runtime <runtime>	Поддерживает "automatic" (использует jsx transform) и "classic" (использует React.createElement)
--jsx-dev	н/д	Bun читает compilerOptions.jsx из tsconfig.json для определения значения по умолчанию. Если compilerOptions.jsx равен "react-jsx" или если NODE_ENV=production Bun будет использовать jsx transform. В противном случае он использует jsxDEV. Бандлер не поддерживает preserve.
--jsx-factory	--jsx-factory
--jsx-fragment	--jsx-fragment
--jsx-import-source	--jsx-import-source
--jsx-side-effects	н/д	Всегда предполагается что JSX не имеет побочных эффектов
--keep-names	н/д	Не поддерживается
--keyfile	н/д	Не применимо
--legal-comments	н/д	Не поддерживается
--log-level	н/д	Не поддерживается. Это можно установить в bunfig.toml как logLevel.
--log-limit	н/д	Не поддерживается
--log-override:X=Y	н/д	Не поддерживается
--main-fields	н/д	Не поддерживается
--mangle-cache	н/д	Не поддерживается
--mangle-props	н/д	Не поддерживается
--mangle-quoted	н/д	Не поддерживается
--metafile	н/д	Не поддерживается
--minify-whitespace	--minify-whitespace
--minify-identifiers	--minify-identifiers
--minify-syntax	--minify-syntax
--out-extension	н/д	Не поддерживается
--outbase	--root
--preserve-symlinks	н/д	Не поддерживается
--public-path	--public-path
--pure	н/д	Не поддерживается
--reserve-props	н/д	Не поддерживается
--resolve-extensions	н/д	Не поддерживается
--servedir	н/д	Не применимо
--source-root	н/д	Не поддерживается
--sourcefile	н/д	Не поддерживается. Bun еще не поддерживает ввод из stdin.
--sourcemap	--sourcemap	Нет различий
--sources-content	н/д	Не поддерживается
--supported	н/д	Не поддерживается
--tree-shaking	н/д	Всегда true
--tsconfig	--tsconfig-override
--version	н/д	Выполните bun --version чтобы увидеть версию Bun.

JavaScript API

esbuild.build()	Bun.build()	Примечания
absWorkingDir	н/д	Всегда установлено в process.cwd()
alias	н/д	Не поддерживается
allowOverwrite	н/д	Всегда false
assetNames	naming.asset	Использует тот же синтаксис шаблонов что и esbuild но [ext] должен быть включен явно. ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> naming: {<br/> asset: "[name].[ext]",<br/> },<br/>});<br/>
banner	н/д	Не поддерживается
bundle	н/д	Всегда true. Используйте Bun.Transpiler для транспиляции без связывания.
charset	н/д	Не поддерживается
chunkNames	naming.chunk	Использует тот же синтаксис шаблонов что и esbuild но [ext] должен быть включен явно. ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> naming: {<br/> chunk: "[name].[ext]",<br/> },<br/>});<br/>
color	н/д	Bun возвращает логи в свойстве logs результата сборки.
conditions	н/д	Не поддерживается. Приоритет условий экспорта определяется target.
define	define
drop	н/д	Не поддерживается
entryNames	naming или naming.entry	Bun поддерживает ключ naming который может быть строкой или объектом. Использует тот же синтаксис шаблонов что и esbuild но [ext] должен быть включен явно. ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> // когда строка это эквивалентно entryNames<br/> naming: "[name].[ext]",<br/><br/> // гранулярные опции naming<br/> naming: {<br/> entry: "[name].[ext]",<br/> asset: "[name].[ext]",<br/> chunk: "[name].[ext]",<br/> },<br/>});<br/>
entryPoints	entrypoints	Различие в капитализации
external	external	Нет различий
footer	н/д	Не поддерживается
format	format	В настоящее время поддерживает только "esm". Поддержка "cjs" и "iife" планируется.
globalName	н/д	Не поддерживается
ignoreAnnotations	н/д	Не поддерживается
inject	н/д	Не поддерживается
jsx	jsx	Не поддерживается в JS API настраивается в tsconfig.json
jsxDev	jsxDev	Не поддерживается в JS API настраивается в tsconfig.json
jsxFactory	jsxFactory	Не поддерживается в JS API настраивается в tsconfig.json
jsxFragment	jsxFragment	Не поддерживается в JS API настраивается в tsconfig.json
jsxImportSource	jsxImportSource	Не поддерживается в JS API настраивается в tsconfig.json
jsxSideEffects	jsxSideEffects	Не поддерживается в JS API настраивается в tsconfig.json
keepNames	н/д	Не поддерживается
legalComments	н/д	Не поддерживается
loader	loader	Bun поддерживает другой набор встроенных загрузчиков чем esbuild; полный справочник смотрите на странице Bundler > Loaders. Загрузчики esbuild dataurl binary base64 copy и empty еще не реализованы.
logLevel	н/д	Не поддерживается
logLimit	н/д	Не поддерживается
logOverride	н/д	Не поддерживается
mainFields	н/д	Не поддерживается
mangleCache	н/д	Не поддерживается
mangleProps	н/д	Не поддерживается
mangleQuoted	н/д	Не поддерживается
metafile	н/д	Не поддерживается
minify	minify	В Bun minify может быть булевым или объектом. ts<br/>await Bun.build({<br/> entrypoints: ['./index.tsx'],<br/> // включить всю минификацию<br/> minify: true<br/><br/> // гранулярные опции<br/> minify: {<br/> identifiers: true,<br/> syntax: true,<br/> whitespace: true<br/> }<br/>})<br/>
minifyIdentifiers	minify.identifiers	Смотрите minify
minifySyntax	minify.syntax	Смотрите minify
minifyWhitespace	minify.whitespace	Смотрите minify
nodePaths	н/д	Не поддерживается
outExtension	н/д	Не поддерживается
outbase	root	Другое имя
outdir	outdir	Нет различий
outfile	outfile	Нет различий
packages	н/д	Не поддерживается используйте external
platform	target	Поддерживает "bun" "node" и "browser" (по умолчанию). Не поддерживает "neutral".
plugins	plugins	API плагинов Bun является подмножеством API esbuild. Некоторые плагины esbuild будут работать из коробки с Bun.
preserveSymlinks	н/д	Не поддерживается
publicPath	publicPath	Нет различий
pure	н/д	Не поддерживается
reserveProps	н/д	Не поддерживается
resolveExtensions	н/д	Не поддерживается
sourceRoot	н/д	Не поддерживается
sourcemap	sourcemap	Поддерживает "inline" "external" и "none"
sourcesContent	н/д	Не поддерживается
splitting	splitting	Нет различий
stdin	н/д	Не поддерживается
supported	н/д	Не поддерживается
target	н/д	Нет поддержки понижения синтаксиса
treeShaking	н/д	Всегда true
tsconfig	н/д	Не поддерживается
write	н/д	Установлено в true если установлен outdir/outfile в противном случае false

Plugin API

API плагинов Bun разработан для совместимости с esbuild. Bun не поддерживает всю поверхность API плагинов esbuild но основная функциональность реализована. Многие сторонние плагины esbuild будут работать из коробки с Bun.

NOTE

В долгосрочной перспективе мы стремимся к паритету функций с API esbuild поэтому если что-то не работает пожалуйста создайте issue чтобы помочь нам определить приоритеты.

Плагины в Bun и esbuild определяются с объектом-билдером.

import type { BunPlugin } from "bun";

const myPlugin: BunPlugin = {
  name: "my-plugin",
  setup(builder) {
    // определить плагин
  },
};

Объект-билдер предоставляет некоторые методы для подключения к частям процесса связывания. Bun реализует onResolve и onLoad; он еще не реализует хуки esbuild onStart onEnd и onDispose и утилиты resolve. initialOptions реализован частично будучи доступным только для чтения и имея только подмножество опций esbuild; используйте вместо этого config (то же самое но с форматом BuildConfig от Bun).

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`