واجهة برمجة تطبيقات حزمة Bun مستوحاة بشدة من esbuild. الترحيل إلى حزمة Bun من esbuild يجب أن يكون غير مؤلم نسبيًا. هذا الدليل سيشرح بإيجاز لماذا قد تفكر في الترحيل إلى حزمة Bun ويوفر مرجع مقارنة واجهة برمجة تطبيقات جنبًا إلى جنب لأولئك الذين هم على دراية بواجهة برمجة تطبيقات esbuild.

هناك بعض الاختلافات السلوكية التي يجب ملاحظتها.

NOTE

**الحزمة افتراضيًا.** على عكس esbuild، Bun يحزم دائمًا افتراضيًا. هذا هو السبب في أن العلم `--bundle` ليس ضروريًا في مثال Bun. لترجمة كل ملف على حدة، استخدم `Bun.Transpiler`.

NOTE

**إنها مجرد حزمة.** على عكس esbuild، حزمة Bun لا تتضمن خادم تطوير مدمج أو مراقب ملفات. إنها مجرد حزمة. الحزمة مخصصة للاستخدام بالاقتران مع `Bun.serve` وواجهات برمجة التطبيقات الأخرى وقت التشغيل لتحقيق نفس التأثير. على هذا النحو، جميع الخيارات المتعلقة بـ HTTP/مراقبة الملفات غير قابلة للتطبيق.

الأداء

مع واجهة برمجة تطبيقات مراعية للأداء مقترنة بمحلل JS/TS القائم على Zig المحسن بشكل كبير، حزمة Bun أسرع بمقدار 1.75x من esbuild في معيار three.js الخاص بـ esbuild.

واجهة سطر الأوامر

كل من Bun و esbuild يوفران واجهة سطر أوامر.

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

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

في واجهة سطر أوامر Bun، الأعلام البسيطة المنطقية مثل --minify لا تقبل وسيطة. الأعلام الأخرى مثل --outdir <path> تقبل وسيطة؛ يمكن كتابة هذه الأعلام كـ --outdir out أو --outdir=out. بعض الأعلام مثل --define يمكن تحديدها عدة مرات: --define foo=bar --define bar=baz.

esbuild	bun build	ملاحظات
--bundle	n/a	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	n/a	غير قابل للتطبيق
--sourcemap	--sourcemap	لا توجد اختلافات
--splitting	--splitting	لا توجد اختلافات
--target	n/a	غير مدعوم. حزمة Bun لا تقوم بخفض البنية النحوية في هذا الوقت.
--watch	--watch	لا توجد اختلافات
--allow-overwrite	n/a	الكتابة فوق غير مسموح بها أبدًا
--analyze	n/a	غير مدعوم
--asset-names	--asset-naming	تم تغيير الاسم للاتساق مع التسمية في واجهة برمجة تطبيقات JS
--banner	--banner	ينطبق فقط على حزم js
--footer	--footer	ينطبق فقط على حزم js
--certfile	n/a	غير قابل للتطبيق
--charset=utf8	n/a	غير مدعوم
--chunk-names	--chunk-naming	تم تغيير الاسم للاتساق مع التسمية في واجهة برمجة تطبيقات JS
--color	n/a	مفعل دائمًا
--drop	--drop
--entry-names	--entry-naming	تم تغيير الاسم للاتساق مع التسمية في واجهة برمجة تطبيقات JS
--global-name	n/a	غير قابل للتطبيق، Bun لا يدعم مخرجات iife في هذا الوقت
--ignore-annotations	--ignore-dce-annotations
--inject	n/a	غير مدعوم
--jsx	--jsx-runtime <runtime>	يدعم "automatic" (يستخدم تحويل jsx) و "classic" (يستخدم React.createElement)
--jsx-dev	n/a	Bun يقرأ compilerOptions.jsx من tsconfig.json لتحديد الافتراضي. إذا كان compilerOptions.jsx هو "react-jsx"، أو إذا كان NODE_ENV=production، سيستخدم Bun تحويل jsx. وإلا، يستخدم jsxDEV. الحزمة لا تدعم preserve.
--jsx-factory	--jsx-factory
--jsx-fragment	--jsx-fragment
--jsx-import-source	--jsx-import-source
--jsx-side-effects	n/a	JSX يُفترض دائمًا أنه خالٍ من الآثار الجانبية
--keep-names	n/a	غير مدعوم
--keyfile	n/a	غير قابل للتطبيق
--legal-comments	n/a	غير مدعوم
--log-level	n/a	غير مدعوم. يمكن تعيين هذا في bunfig.toml كـ logLevel.
--log-limit	n/a	غير مدعوم
--log-override:X=Y	n/a	غير مدعوم
--main-fields	n/a	غير مدعوم
--mangle-cache	n/a	غير مدعوم
--mangle-props	n/a	غير مدعوم
--mangle-quoted	n/a	غير مدعوم
--metafile	n/a	غير مدعوم
--minify-whitespace	--minify-whitespace
--minify-identifiers	--minify-identifiers
--minify-syntax	--minify-syntax
--out-extension	n/a	غير مدعوم
--outbase	--root
--preserve-symlinks	n/a	غير مدعوم
--public-path	--public-path
--pure	n/a	غير مدعوم
--reserve-props	n/a	غير مدعوم
--resolve-extensions	n/a	غير مدعوم
--servedir	n/a	غير قابل للتطبيق
--source-root	n/a	غير مدعوم
--sourcefile	n/a	غير مدعوم. Bun لا يدعم إدخال stdin بعد.
--sourcemap	--sourcemap	لا توجد اختلافات
--sources-content	n/a	غير مدعوم
--supported	n/a	غير مدعوم
--tree-shaking	n/a	صحيح دائمًا
--tsconfig	--tsconfig-override
--version	n/a	شغّل bun --version لرؤية إصدار Bun.

واجهة برمجة تطبيقات JavaScript

esbuild.build()	Bun.build()	ملاحظات
absWorkingDir	n/a	مضبوط دائمًا على process.cwd()
alias	n/a	غير مدعوم
allowOverwrite	n/a	خاطئ دائمًا
assetNames	naming.asset	يستخدم نفس بنية القالب مثل esbuild، لكن [ext] يجب تضمينه صراحة. ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> naming: {<br/> asset: "[name].[ext]",<br/> },<br/>});<br/>
banner	n/a	غير مدعوم
bundle	n/a	صحيح دائمًا. استخدم Bun.Transpiler للترجمة بدون حزمة.
charset	n/a	غير مدعوم
chunkNames	naming.chunk	يستخدم نفس بنية القالب مثل esbuild، لكن [ext] يجب تضمينه صراحة. ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> naming: {<br/> chunk: "[name].[ext]",<br/> },<br/>});<br/>
color	n/a	Bun يعيد السجلات في خاصية logs من نتيجة البناء.
conditions	n/a	غير مدعوم. أولوية شروط التصدير تحددها target.
define	define
drop	n/a	غير مدعوم
entryNames	naming أو naming.entry	Bun يدعم مفتاح naming الذي يمكن أن يكون إما سلسلة أو كائن. يستخدم نفس بنية القالب مثل esbuild، لكن [ext] يجب تضمينه صراحة. ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> // عندما يكون سلسلة، هذا يعادل entryNames<br/> naming: "[name].[ext]",<br/><br/> // خيارات تسمية دقيقة<br/> naming: {<br/> entry: "[name].[ext]",<br/> asset: "[name].[ext]",<br/> chunk: "[name].[ext]",<br/> },<br/>});<br/>
entryPoints	entrypoints	فرق في الأحرف الكبيرة
external	external	لا توجد اختلافات
footer	n/a	غير مدعوم
format	format	يدعم فقط "esm" حاليًا. دعم "cjs" و "iife" مخطط له.
globalName	n/a	غير مدعوم
ignoreAnnotations	n/a	غير مدعوم
inject	n/a	غير مدعوم
jsx	jsx	غير مدعوم في واجهة برمجة تطبيقات JS، اضبط في tsconfig.json
jsxDev	jsxDev	غير مدعوم في واجهة برمجة تطبيقات JS، اضبط في tsconfig.json
jsxFactory	jsxFactory	غير مدعوم في واجهة برمجة تطبيقات JS، اضبط في tsconfig.json
jsxFragment	jsxFragment	غير مدعوم في واجهة برمجة تطبيقات JS، اضبط في tsconfig.json
jsxImportSource	jsxImportSource	غير مدعوم في واجهة برمجة تطبيقات JS، اضبط في tsconfig.json
jsxSideEffects	jsxSideEffects	غير مدعوم في واجهة برمجة تطبيقات JS، اضبط في tsconfig.json
keepNames	n/a	غير مدعوم
legalComments	n/a	غير مدعوم
loader	loader	Bun يدعم مجموعة مختلفة من المحملات المدمجة عن esbuild؛ راجع Bundler > Loaders للحصول على مرجع كامل. محملات esbuild dataurl و binary و base64 و copy و empty لم يتم تنفيذها بعد.
logLevel	n/a	غير مدعوم
logLimit	n/a	غير مدعوم
logOverride	n/a	غير مدعوم
mainFields	n/a	غير مدعوم
mangleCache	n/a	غير مدعوم
mangleProps	n/a	غير مدعوم
mangleQuoted	n/a	غير مدعوم
metafile	n/a	غير مدعوم
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	n/a	غير مدعوم
outExtension	n/a	غير مدعوم
outbase	root	اسم مختلف
outdir	outdir	لا توجد اختلافات
outfile	outfile	لا توجد اختلافات
packages	n/a	غير مدعوم، استخدم external
platform	target	يدعم "bun" و "node" و "browser" (الافتراضي). لا يدعم "neutral".
plugins	plugins	واجهة برمجة تطبيقات المكونات الإضافية في Bun هي مجموعة فرعية من esbuild. بعض مكونات esbuild الإضافية ستعمل مباشرة مع Bun.
preserveSymlinks	n/a	غير مدعوم
publicPath	publicPath	لا توجد اختلافات
pure	n/a	غير مدعوم
reserveProps	n/a	غير مدعوم
resolveExtensions	n/a	غير مدعوم
sourceRoot	n/a	غير مدعوم
sourcemap	sourcemap	يدعم "inline" و "external" و "none"
sourcesContent	n/a	غير مدعوم
splitting	splitting	لا توجد اختلافات
stdin	n/a	غير مدعوم
supported	n/a	غير مدعوم
target	n/a	لا دعم لخفض البنية النحوية
treeShaking	n/a	صحيح دائمًا
tsconfig	n/a	غير مدعوم
write	n/a	مضبوط على صحيح إذا تم تعيين outdir/outfile، وإلا خاطئ

واجهة برمجة تطبيقات المكونات الإضافية

واجهة برمجة تطبيقات المكونات الإضافية في Bun مصممة لتكون متوافقة مع esbuild. Bun لا يدعم كامل سطح واجهة برمجة تطبيقات المكونات الإضافية في esbuild، لكن الوظيفة الأساسية تم تنفيذها. العديد من مكونات esbuild الإضافية التابعة لجهات خارجية ستعمل مباشرة مع Bun.

NOTE

على المدى الطويل، نهدف إلى تكافؤ الميزات مع واجهة برمجة تطبيقات esbuild، لذا إذا كان شيء ما لا يعمل يرجى تقديم مشكلة لمساعدتنا في تحديد الأولويات.

المكونات الإضافية في Bun و esbuild محددة بكائن منشئ.

myPlugin.ts

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) بدلاً من ذلك.

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

الخيارات

- 🟢 `filter`
- 🟢 `namespace`

الوسائط

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

النتائج

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

onLoad

الخيارات

- 🟢 `filter`
- 🟢 `namespace`

الوسائط

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

النتائج

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