يمكن تكوين سلوك Bun باستخدام ملف التكوين الخاص به bunfig.toml.

بشكل عام، يعتمد Bun على ملفات التكوين الموجودة مسبقًا مثل package.json وtsconfig.json لتكوين سلوكه. يكون bunfig.toml ضروريًا فقط لتكوين الأشياء الخاصة بـ Bun. هذا الملف اختياري، وسيعمل Bun بدون أي إعدادات إضافية.

عام مقابل محلي

بشكل عام، يُوصى بإضافة ملف bunfig.toml إلى جذر مشروعك، بجانب package.json.

لتكوين Bun عالميًا، يمكنك أيضًا إنشاء ملف .bunfig.toml في أحد المسارات التالية:

• $HOME/.bunfig.toml
• $XDG_CONFIG_HOME/.bunfig.toml

إذا تم اكتشاف كل من bunfig العالمي والمحلي، يتم دمج النتائج بشكل سطحي، مع تجاوز المحلي للعالمي. ستتجاوز أعلام سطر الأوامر إعداد bunfig حيثما ينطبق ذلك.

وقت التشغيل

يتم تكوين سلوك وقت تشغيل Bun باستخدام الحقول ذات المستوى الأعلى في ملف bunfig.toml.

preload

مصفوفة من البرامج النصية/الإضافات لتنفيذها قبل تشغيل ملف أو برنامج نصي.

bunfig.toml

# البرامج النصية لتشغيلها قبل `bun run` لملف أو برنامج نصي
# سجل الإضافات عن طريق إضافتها إلى هذه القائمة
preload = ["./preload.ts"]

jsx

تكوين كيفية تعامل Bun مع JSX. يمكنك أيضًا تعيين هذه الحقول في compilerOptions من tsconfig.json، ولكنها مدعومة هنا أيضًا لمشاريع غير TypeScript.

bunfig.toml

jsx = "react"
jsxFactory = "h"
jsxFragment = "Fragment"
jsxImportSource = "react"

راجع توثيق tsconfig لمزيد من المعلومات حول هذه الحقول.

• jsx
• jsxFactory
• jsxFragment
• jsxImportSource

smol

تفعيل وضع smol. يقلل هذا من استخدام الذاكرة على حساب الأداء.

bunfig.toml

# تقليل استخدام الذاكرة على حساب الأداء
smol = true

logLevel

تعيين مستوى السجل. يمكن أن يكون أحد "debug" أو "warn" أو "error".

bunfig.toml

logLevel = "debug" # "debug" | "warn" | "error"

define

يسمح لك حقل define باستبدال بعض المعرفات العامة بتعبيرات ثابتة. سيقوم Bun باستبدال أي استخدام للمعرف بالتعبير. يجب أن يكون التعبير سلسلة JSON.

bunfig.toml

[define]
# استبدال أي استخدام لـ "process.env.bagel" بالسلسلة `lox`.
# يتم تحليل القيم كـ JSON، باستثناء دعم السلاسل ذات الاقتباس المفرد وتصبح `'undefined'` قيمة `undefined` في JS.
# من المحتمل أن يتغير هذا في إصدار مستقبلي إلى TOML عادي بدلاً من ذلك. إنه بقايا من تحليل وسيطة سطر الأوامر.
"process.env.bagel" = "'lox'"

loader

تكوين كيفية تعيين Bun لامتدادات الملفات إلى المحملات. هذا مفيد لتحميل الملفات غير المدعومة أصليًا بواسطة Bun.

bunfig.toml

[loader]
# عند استيراد ملف .bagel، تعامل معه كملف tsx
".bagel" = "tsx"

يدعم Bun المحملات التالية:

• jsx
• js
• ts
• tsx
• css
• file
• json
• toml
• wasm
• napi
• base64
• dataurl
• text

telemetry

يُستخدم حقل telemetry لتفعيل/تعطيل التحليلات. افتراضيًا، يتم تفعيل القياس عن بعد. هذا يعادل متغير البيئة DO_NOT_TRACK.

حاليًا لا نجمع القياس عن بعد ويُستخدم هذا الإعداد فقط لتفعيل/تعطيل تقارير الأعطال المجهولة، لكننا نخطط في المستقبل لجمع معلومات مثل واجهات برمجة تطبيقات Bun الأكثر استخدامًا أو المدة التي يستغرقها bun build.

bunfig.toml

telemetry = false

console

تكوين سلوك إخراج وحدة التحكم.

console.depth

تعيين العمق الافتراضي لفحص كائن console.log(). الافتراضي 2.

bunfig.toml

[console]
depth = 3

يتحكم هذا في مدى عمق عرض الكائنات المتداخلة في إخراج وحدة التحكم. تُظهر القيم الأعلى خصائص متداخلة أكثر ولكن قد تنتج إخراجًا مطولاً للكائنات المعقدة. يمكن تجاوز هذا الإعداد بواسطة علم CLI --console-depth.

مختبر الاختبارات

يتم تكوين مختبر الاختبارات تحت قسم [test] في bunfig.toml الخاص بك.

bunfig.toml

[test]
# التكوين هنا

test.root

دليل الجذر لتشغيل الاختبارات منه. الافتراضي ..

bunfig.toml

[test]
root = "./__tests__"

test.preload

نفس حقل preload ذو المستوى الأعلى، ولكن ينطبق فقط على bun test.

bunfig.toml

[test]
preload = ["./setup.ts"]

test.smol

نفس حقل smol ذو المستوى الأعلى، ولكن ينطبق فقط على bun test.

bunfig.toml

[test]
smol = true

test.coverage

يفعّل تقارير التغطية. الافتراضي false. استخدم --coverage للتجاوز.

bunfig.toml

[test]
coverage = false

test.coverageThreshold

لتحديد عتبة التغطية. افتراضيًا، لم يتم تعيين أي عتبة. إذا لم تلبِ مجموعة الاختبارات هذه العتبة أو تتجاوزها، فسيخرج bun test برمز خروج غير صفري للإشارة إلى الفشل.

bunfig.toml

[test]

# لطلب تغطية بنسبة 90% على مستوى السطر وعلى مستوى الدالة
coverageThreshold = 0.9

يمكن تحديد عتبات مختلفة للتغطية على مستوى السطر وعلى مستوى الدالة وعلى مستوى العبارة.

bunfig.toml

[test]
coverageThreshold = { line = 0.7, function = 0.8, statement = 0.9 }

test.coverageSkipTestFiles

ما إذا كان يجب تخطي ملفات الاختبار عند حساب إحصائيات التغطية. الافتراضي false.

bunfig.toml

[test]
coverageSkipTestFiles = false

test.coveragePathIgnorePatterns

استبعاد ملفات أو أنماط ملفات محددة من تقارير التغطية باستخدام أنماط glob. يمكن أن يكون نمط سلسلة واحد أو مصفوفة من الأنماط.

bunfig.toml

[test]
# نمط واحد
coveragePathIgnorePatterns = "**/*.spec.ts"

# أنماط متعددة
coveragePathIgnorePatterns = [
  "**/*.spec.ts",
  "**/*.test.ts",
  "src/utils/**",
  "*.config.js"
]

test.coverageReporter

افتراضيًا، سيتم طباعة تقارير التغطية إلى وحدة التحكم. لتقارير تغطية الكود المستمرة في بيئات CI وللأدوات الأخرى استخدم lcov.

bunfig.toml

[test]
coverageReporter  = ["text", "lcov"]  # الافتراضي ["text"]

test.coverageDir

تعيين المسار حيث سيتم حفظ تقارير التغطية. يرجى ملاحظة، أنه يعمل فقط لـ coverageReporter المستمرة مثل lcov.

bunfig.toml

[test]
coverageDir = "path/to/somewhere"  # الافتراضي "coverage"

test.randomize

تشغيل الاختبارات بترتيب عشوائي. الافتراضي false.

bunfig.toml

[test]
randomize = true

هذا يساعد في اكتشاف الأخطاء المتعلقة بالاعتماد المتبادل بين الاختبارات عن طريق تشغيل الاختبارات بترتيب مختلف في كل مرة. عند دمجه مع seed، يصبح الترتيب العشوائي قابلًا للتكرار.

سيتجاوز علم CLI --randomize هذا الإعداد عند تحديده.

test.seed

تعيين البذرة العشوائية لت عشوائية الاختبار. يتطلب هذا الخيار أن يكون randomize بقيمة true.

bunfig.toml

[test]
randomize = true
seed = 2444615283

استخدام بذرة يجعل ترتيب الاختبار العشوائي قابلًا للتكرار عبر عمليات التشغيل، وهو مفيد لتصحيح الاختبارات غير المستقرة. عند مواجهة فشل اختبار مع تفعيل العشوائية، يمكنك استخدام نفس البذرة لإعادة إنتاج ترتيب الاختبار الدقيق.

سيتجاوز علم CLI --seed هذا الإعداد عند تحديده.

test.rerunEach

إعادة تشغيل كل ملف اختبار عدد محدد من المرات. الافتراضي 0 (تشغيل مرة واحدة).

bunfig.toml

[test]
rerunEach = 3

هذا مفيد لاكتشاف الاختبارات غير المستقرة أو السلوك غير الحتمي. سيتم تنفيذ كل ملف اختبار العدد المحدد من المرات.

سيتجاوز علم CLI --rerun-each هذا الإعداد عند تحديده.

test.concurrentTestGlob

تحديد نمط glob لتشغيل ملفات الاختبار المطابقة تلقائيًا مع تفعيل تنفيذ الاختبار المتزامن. ستتصرف ملفات الاختبار المطابقة لهذا النمط كما لو تم تمرير العلم --concurrent، مما يشغل جميع الاختبارات داخل تلك الملفات بشكل متزامن.

bunfig.toml

[test]
concurrentTestGlob = "**/concurrent-*.test.ts"

هذا مفيد لـ:

• ترحيل مجموعات الاختبارات تدريجيًا إلى التنفيذ المتزامن
• تشغيل اختبارات التكامل بشكل متزامن مع الحفاظ على اختبارات الوحدة متسلسلة
• فصل الاختبارات المتزامنة السريعة عن الاختبارات التي تتطلب تنفيذًا متسلسلاً

سيتجاوز علم CLI --concurrent هذا الإعداد عند تحديده.

test.onlyFailures

عند التفعيل، يتم عرض الاختبارات الفاشلة فقط في الإخراج. هذا يساعد في تقليل الضوضاء في مجموعات الاختبارات الكبيرة عن طريق إخفاء الاختبارات الناجحة. الافتراضي false.

bunfig.toml

[test]
onlyFailures = true

هذا يعادل استخدام العلم --only-failures عند تشغيل bun test.

test.reporter

تكوين إعدادات مُبلغ الاختبار.

test.reporter.dots

تفعيل مُبلغ النقاط، الذي يعرض إخراجًا مضغوطًا يُظهر نقطة لكل اختبار. الافتراضي false.

bunfig.toml

[test.reporter]
dots = true

test.reporter.junit

تفعيل تقارير JUnit XML وتحديد مسار ملف الإخراج.

bunfig.toml

[test.reporter]
junit = "test-results.xml"

هذا ينشئ تقرير JUnit XML يمكن استهلاكه بواسطة أنظمة CI والأدوات الأخرى.

مدير الحزم

إدارة الحزم قضية معقدة؛ لدعم مجموعة من حالات الاستخدام، يمكن تكوين سلوك bun install تحت قسم [install].

bunfig.toml

[install]
# التكوين هنا

install.optional

ما إذا كان سيتم تثبيت التبعيات الاختيارية. الافتراضي true.

bunfig.toml

[install]
optional = true

install.dev

ما إذا كان سيتم تثبيت تبعيات التطوير. الافتراضي true.

bunfig.toml

[install]
dev = true

install.peer

ما إذا كان سيتم تثبيت تبعيات الأقران. الافتراضي true.

bunfig.toml

[install]
peer = true

install.production

ما إذا كان bun install سيعمل في "وضع الإنتاج". الافتراضي false.

في وضع الإنتاج، لا يتم تثبيت "devDependencies". يمكنك استخدام --production في CLI لتجاوز هذا الإعداد.

bunfig.toml

[install]
production = false

install.exact

ما إذا كان سيتم تعيين إصدار دقيق في package.json. الافتراضي false.

افتراضيًا يستخدم Bun نطاقات caret؛ إذا كان الإصدار latest من حزمة هو 2.4.1، فسيكون نطاق الإصدار في package.json الخاص بك هو ^2.4.1. هذا يشير إلى أن أي إصدار من 2.4.1 حتى (ولكن لا يشمل) 3.0.0 مقبول.

bunfig.toml

[install]
exact = false

install.saveTextLockfile

إذا كان false، فأنشئ bun.lockb ثنائي بدلاً من ملف bun.lock نصي عند تشغيل bun install وعدم وجود ملف قفل.

الافتراضي true (منذ Bun v1.2).

bunfig.toml

[install]
saveTextLockfile = false

install.auto

لتكوين سلوك التثبيت التلقائي للحزم لـ Bun. الافتراضي "auto" — عند عدم العثور على مجلد node_modules، سيقوم Bun تلقائيًا بتثبيت التبعيات أثناء التنفيذ.

bunfig.toml

[install]
auto = "auto"

القيم الصالحة هي:

القيمة	الوصف
"auto"	حل الوحدات من node_modules المحلي إذا كان موجودًا. خلاف ذلك، تثبيت التبعيات تلقائيًا أثناء التنفيذ.
"force"	تثبيت التبعيات تلقائيًا دائمًا، حتى إذا كان node_modules موجودًا.
"disable"	عدم تثبيت التبعيات تلقائيًا أبدًا.
"fallback"	التحقق من node_modules المحلي أولاً، ثم التثبيت التلقائي لأي حزم غير موجودة. يمكنك تفعيل هذا من CLI باستخدام bun -i.

install.frozenLockfile

عندما يكون true، لن يقوم bun install بتحديث bun.lock. الافتراضي false. إذا كان package.json وbun.lock الحالي غير متوافقين، فسيحدث خطأ.

bunfig.toml

[install]
frozenLockfile = false

install.dryRun

ما إذا كان bun install سيقوم فعليًا بتثبيت التبعيات. الافتراضي false. عندما يكون true، فهو يعادل تعيين --dry-run على جميع أوامر bun install.

bunfig.toml

[install]
dryRun = false

install.globalDir

لتكوين الدليل حيث يضع Bun الحزم المثبتة عالميًا.

متغير البيئة: BUN_INSTALL_GLOBAL_DIR

bunfig.toml

[install]
# حيث يقوم `bun install --global` بتثبيت الحزم
globalDir = "~/.bun/install/global"

install.globalBinDir

لتكوين الدليل حيث يقوم Bun بتثبيت الملفات الثنائية وCLIs المثبتة عالميًا.

متغير البيئة: BUN_INSTALL_BIN

bunfig.toml

[install]
# حيث يتم ربط bins الحزم المثبتة عالميًا
globalBinDir = "~/.bun/bin"

install.registry

السجل الافتراضي هو https://registry.npmjs.org/. يمكن تكوين هذا عالميًا في bunfig.toml:

bunfig.toml

[install]
# تعيين السجل الافتراضي كسلسلة
registry = "https://registry.npmjs.org"
# تعيين رمز مميز
registry = { url = "https://registry.npmjs.org", token = "123456" }
# تعيين اسم مستخدم/كلمة مرور
registry = "https://username:password@registry.npmjs.org"

install.linkWorkspacePackages

لتكوين كيفية ربط حزم مساحة العمل، استخدم خيار install.linkWorkspacePackages.

ما إذا كان سيتم ربط حزم مساحة العمل من جذر monorepo إلى أدلة node_modules الخاصة بها. الافتراضي true.

bunfig.toml

[install]
linkWorkspacePackages = true

install.scopes

لتكوين سجل لنطاق معين (مثل @myorg/<package>) استخدم install.scopes. يمكنك الرجوع إلى متغيرات البيئة باستخدام تدوين $variable.

bunfig.toml

[install.scopes]
# السجل كسلسلة
myorg = "https://username:password@registry.myorg.com/"

# السجل مع اسم مستخدم/كلمة مرور
# يمكنك الرجوع إلى متغيرات البيئة
myorg = { username = "myusername", password = "$npm_password", url = "https://registry.myorg.com/" }

# السجل مع رمز مميز
myorg = { token = "$npm_token", url = "https://registry.myorg.com/" }

install.ca وinstall.cafile

لتكوين شهادة CA، استخدم install.ca أو install.cafile لتحديد مسار إلى ملف شهادة CA.

bunfig.toml

[install]
# شهادة CA كسلسلة
ca = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"

# مسار إلى ملف شهادة CA. يمكن أن يحتوي الملف على شهادات متعددة.
cafile = "path/to/cafile"

install.cache

لتكوين سلوك التخزين المؤقت:

bunfig.toml

[install.cache]

# الدليل لاستخدامه للتخزين المؤقت
dir = "~/.bun/install/cache"

# عندما يكون true، لا تقم بالتحميل من التخزين المؤقت العالمي.
# قد لا يزال Bun يكتب إلى node_modules/.cache
disable = false

# عندما يكون true، قم دائمًا بحل أحدث الإصدارات من السجل
disableManifest = false

install.lockfile

لتكوين سلوك ملف القفل، استخدم قسم install.lockfile.

ما إذا كان سيتم إنشاء ملف قفل عند bun install. الافتراضي true.

bunfig.toml

[install.lockfile]
save = true

ما إذا كان سيتم إنشاء ملف قفل غير Bun بجانب bun.lock. (سيتم دائمًا إنشاء bun.lock.) حاليًا "yarn" هي القيمة الوحيدة المدعومة.

bunfig.toml

[install.lockfile]
print = "yarn"

install.linker

تكوين استراتيجية الرابط لتثبيت التبعيات. الافتراضي "isolated" لمساحات العمل الجديدة، "hoisted" لمشاريع الحزمة الفردية الجديدة والمشاريع الموجودة (المصنوعة قبل v1.3.2).

للحصول على التوثيق الكامل راجع مدير الحزم > التثبيتات المعزولة.

bunfig.toml

[install]
linker = "hoisted"

القيم الصالحة هي:

القيمة	الوصف
"hoisted"	ربط التبعيات في دليل node_modules مشترك.
"isolated"	ربط التبعيات داخل كل تثبيت حزمة.

bunfig.toml

[debug]
# عند التنقل إلى رابط blob: أو src:، افتح الملف في محررك
# إذا لم يكن كذلك، يحاول $EDITOR أو $VISUAL
# إذا فشل ذلك أيضًا، سيحاول Visual Studio Code، ثم Sublime Text، ثم البعض الآخر
# يُستخدم هذا بواسطة Bun.openInEditor()
editor = "code"

# قائمة المحررين:
# - "subl", "sublime"
# - "vscode", "code"
# - "textmate", "mate"
# - "idea"
# - "webstorm"
# - "nvim", "neovim"
# - "vim","vi"
# - "emacs"

install.security.scanner

تكوين أمان ماسح ضوئي لمسح الحزم بحثًا عن الثغرات الأمنية قبل التثبيت.

أولاً، قم بتثبيت ماسح أمان من npm:

bun add -d @acme/bun-security-scanner

ثم قم بتكوينه في bunfig.toml الخاص بك:

[install.security]
scanner = "@acme/bun-security-scanner"

عند تكوين ماسح أمان:

• يتم تعطيل التثبيت التلقائي تلقائيًا للأمان
• يتم مسح الحزم قبل التثبيت
• يتم إلغاء التثبيت إذا تم العثور على مشكلات قاتلة
• يتم عرض تحذيرات الأمان أثناء التثبيت

تعرف على المزيد حول استخدام وكتابة ماسحات الأمان.

install.minimumReleaseAge

تكوين الحد الأدنى للعمر (بالثواني) لإصدارات حزم npm. سيتم تصفية إصدارات الحزم التي تم نشرها مؤخرًا أكثر من هذه العتبة أثناء التثبيت. الافتراضي هو null (معطل).

bunfig.toml

[install]
# تثبيت إصدارات الحزم التي تم نشرها قبل 3 أيام على الأقل
minimumReleaseAge = 259200
# ستتجاوز هذه الحزم متطلبات الحد الأدنى للعمر لمدة 3 أيام
minimumReleaseAgeExcludes = ["@types/bun", "typescript"]

لمزيد من التفاصيل راجع الحد الأدنى لعمر الإصدار في توثيق التثبيت.

bun run

يمكن تكوين أمر bun run تحت قسم [run]. ينطبق هذا على أمر bun run وأمر bun عند تشغيل ملف أو ملف تنفيذي أو برنامج نصي.

حاليًا، يتم تحميل bunfig.toml تلقائيًا فقط لـ bun run في مشروع محلي (لا يتحقق من .bunfig.toml عالمي).

run.shell - استخدام shell النظام أو shell لـ Bun

الـ shell لاستخدامه عند تشغيل برامج package.json النصية عبر bun run أو bun. على Windows، الافتراضي هو "bun" وعلى المنصات الأخرى الافتراضي هو "system".

لاستخدام shell النظام دائمًا بدلاً من shell لـ Bun (السلوك الافتراضي ما لم يكن Windows):

bunfig.toml

[run]
# الافتراضي خارج Windows
shell = "system"

لاستخدام shell لـ Bun دائمًا بدلاً من shell النظام:

bunfig.toml

[run]
# الافتراضي على Windows
shell = "bun"

run.bun - ربط node تلقائيًا بـ bun

عندما يكون true، يسبق هذا $PATH برابط رمزي لـ node يشير إلى الملف الثنائي bun لجميع البرامج النصية أو الملفات التنفيذية التي يستدعيها bun run أو bun.

هذا يعني أنه إذا كان لديك برنامج نصي يشغل node، فسيشغل فعليًا bun بدلاً من ذلك، دون الحاجة إلى تغيير البرنامج النصي الخاص بك. يعمل هذا بشكل متكرر، لذا إذا شغل البرنامج النصي الخاص بك برنامجًا نصيًا آخر يشغل node، فسيشغل bun بدلاً من ذلك. ينطبق هذا على shebangs أيضًا، لذا إذا كان لديك برنامج نصي به shebang يشير إلى node، فسيشغل فعليًا bun بدلاً من ذلك.

افتراضيًا، يتم تفعيل هذا إذا لم يكن node موجودًا بالفعل في $PATH الخاص بك.

bunfig.toml

[run]
# يعادل `bun --bun` لجميع أوامر `bun run`
bun = true

يمكنك اختبار هذا عن طريق التشغيل:

bun --bun which node # /path/to/bun
bun which node # /path/to/node

هذا الخيار يعادل إضافة البادئة --bun لجميع أوامر bun run:

bun --bun run dev
bun --bun dev
bun run --bun dev

إذا تم تعيينه إلى false، فسيؤدي هذا إلى تعطيل الرابط الرمزي لـ node.

run.silent - كتم إخراج الأمر الذي يتم تشغيله

عندما يكون true، يكتم إخراج الأمر الذي يتم تشغيله بواسطة bun run أو bun.

bunfig.toml

[run]
silent = true

بدون هذا الخيار، سيتم طباعة الأمر الذي يتم تشغيله إلى وحدة التحكم:

bun run dev
echo "Running \"dev\"..."

Running "dev"...

مع هذا الخيار، لن يتم طباعة الأمر الذي يتم تشغيله إلى وحدة التحكم:

bun run dev

Running "dev"...

هذا يعادل تمرير --silent إلى جميع أوامر bun run:

bun --silent run dev
bun --silent dev
bun run --silent dev