التحول من ESLint + Prettier إلى

Biome هي أداة واحدة مبنية بلغة Rust تحل محل كل من ESLint و Prettier. قم بتثبيتها، ثم شغّل biome migrate eslint و biome migrate prettier لتحويل إعداداتك الحالية إلى ملف biome.json واحد، ثم شغّل biome check --write لفحص الأخطاء (lint) وتنسيق مشروعك في خطوة واحدة.¹

ملخص

ستقوم بأخذ مشروع JavaScript صغير يستخدم ESLint و Prettier ونقله إلى Biome 2.5.0 في حوالي عشر دقائق. سنقوم بتثبيت Biome، وإنشاء ملف إعداد باستخدام biome init، وتهجير إعدادات ESLint و Prettier الحالية تلقائيًا، وتشغيل فاحص التنسيق والأخطاء المدمج، وربط سكربتات npm، وإضافة بوابة CI. تم تشغيل كل أمر ومخرج أدناه على Node.js 22.22.3. لا توجد لقطات شاشة — هذا عمل خالص عبر التيرمينال.

ما ستتعلمه

• لماذا تستبدل الفرق ESLint + Prettier بـ Biome، وما هي المقايضات
• كيفية تثبيت وتثبيت إصدار Biome 2.5.0 وإنشاء هيكل biome.json
• كيفية تهجير إعدادات ESLint الحالية باستخدام biome migrate eslint
• كيفية تهجير إعدادات Prettier وملف .prettierignore باستخدام biome migrate prettier
• كيفية فحص الأخطاء والتنسيق في خطوة واحدة باستخدام biome check، بما في ذلك الإصلاحات الآمنة وغير الآمنة
• كيفية إضافة سكربتات npm وبوابة CI باستخدام biome ci
• كيفية جعل Biome يحترم ملف .gitignore الخاص بك
• كيفية استكشاف الأخطاء وإصلاحها للأشياء الخمسة التي تعيق الناس فعليًا

المتطلبات الأساسية

• Node.js 20 أو أحدث (تم الاختبار على 22.22.3). يتم شحن Biome كملف ثنائي أصلي مبني مسبقًا عبر npm، لذا لا يوجد شيء ليتم تجميعه.¹
• مشروع موجود يستخدم بالفعل ESLint (سواء flat أو legacy .eslintrc*) و Prettier. إذا لم يكن لديك واحد، فإن الخطوة التالية تنشئ مشروعًا بسيطًا يمكنك نسخه ولصقه.
• تيرمينال. هذا كل شيء — ليس لدى Biome أي تبعيات نظيرة (peer dependencies) ولا يحتاج إلى حزمة TypeScript لفحص TypeScript.²

لماذا Biome بدلاً من ESLint + Prettier

ESLint و Prettier هما أداتان، وملفا إعداد، وشجرتا تبعيات، ومروران على الكود الخاص بك. يقوم Biome بدمجهما في ملف ثنائي واحد مع إعداد واحد. تشير أرقام Biome المنشورة إلى أنه متوافق بنسبة 97% مع تنسيق Prettier وأسرع بحوالي 35 مرة من Prettier في اختباره المرجعي المكون من 171,127 سطرًا عبر 2,104 ملفًا.³ نظرًا لأن Biome 2.0 أضاف محرك استنتاج أنواع خفيف الوزن، يمكنه تشغيل قواعد فحص الأخطاء المدركة للأنواع دون استدعاء مترجم TypeScript أو تثبيت حزمة TypeScript، وهو ما يحافظ على سرعته.²

المقايضة الصادقة: تلك النسبة المتبقية البالغة 3% من اختلافات Prettier قد تهم بعض الفرق، ومجموعة قواعد Biome — رغم تجاوزها 500 قاعدة فحص بدءًا من الإصدار v2.5 — لا تغطي كل إضافات ESLint التي قد تعتمد عليها.⁴ تخبرك أوامر التهجير أدناه بالضبط بالنسبة المئوية لقواعدك التي يمكن لـ Biome إعادة إنتاجها، حتى تتمكن من اتخاذ هذا القرار بناءً على البيانات بدلاً من التخمين.

الخطوة 1: ابدأ بمشروع ESLint + Prettier حقيقي

أنشئ مشروعًا صغيرًا بحيث تكون كل المخرجات في هذا الدليل قابلة لإعادة الإنتاج. يحتوي ملف المصدر على مشاكل فحص متعمدة (مساواة فضفاضة، متغير غير مستخدم، console.log تائه، let يجب أن يكون const) وتنسيق سيئ.

mkdir biome-demo && cd biome-demo
npm init -y

أضف إعداد ESLint قديم (.eslintrc.json):

{
  "root": true,
  "rules": {
    "no-unused-vars": "error",
    "no-console": "warn",
    "eqeqeq": "error",
    "prefer-const": "error"
  }
}

أضف إعداد Prettier (.prettierrc):

{
  "semi": false,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "all",
  "printWidth": 100
}

أضف ملف .prettierignore:

dist
coverage

وملف مصدر فوضوي في src/total.js:

let   label = "cart"
const taxRate = 0.2
const unusedTotal = 0

function total(items, applyTax){
    let sum = 0
    for (const i of items){
        sum = sum + i.price
    }
if (applyTax == true){
        console.log("applying tax")
        sum = sum * (1 + taxRate)
    }
    return sum
}

export {total, label}

الخطوة 2: تثبيت وتثبيت إصدار Biome

قم بتثبيت Biome كـ dev dependency وقم بتثبيت الإصدار المحدد حتى يقوم CI وكل زميل في الفريق بتشغيل نفس الملف الثنائي تمامًا. تثبيت الإصدار مهم: يشحن Biome قواعد جديدة ومحدثة في الإصدارات الفرعية، لذا فإن التثبيت غير المحدد يمكن أن يغير أي التشخيصات التي يتم إطلاقها.⁴

npm install -D @biomejs/biome@2.5.0
npx biome --version

Version: 2.5.0

الآن قم بإنشاء هيكل الإعداد:

npx biome init

يؤدي هذا إلى كتابة ملف biome.json ابتدائي. تعمل الإعدادات الافتراضية على تمكين المنسق (إزاحة tab)، وفاحص الأخطاء مع الإعداد المسبق recommended، وفرز الاستيرادات — وتتضمن كتلة vcs (معطلة افتراضيًا) والتي سنقوم بتفعيلها في الخطوة 8:

{
  "$schema": "https://biomejs.dev/schemas/2.5.0/schema.json",
  "vcs": {
    "enabled": false,
    "clientKind": "git",
    "useIgnoreFile": false
  },
  "files": {
    "ignoreUnknown": false
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "tab"
  },
  "linter": {
    "enabled": true,
    "rules": {
      "preset": "recommended"
    }
  },
  "JavaScript": {
    "formatter": {
      "quoteStyle": "double"
    }
  },
  "assist": {
    "enabled": true,
    "actions": {
      "source": {
        "organizeImports": "on"
      }
    }
  }
}

لاحظ "preset": "recommended". بدءًا من الإصدار v2.5، أصبح مفتاح "recommended": true القديم مهجورًا لصالح linter.rules.preset؛ كلاهما لا يزال يعمل، لكن biome init و biome migrate يصدران الآن preset، وتشغيل biome migrate --write يعيد كتابة المفتاح القديم لك.⁴ لا تزال العديد من الدروس القديمة تعرض recommended: true — هذا هو الشكل المهجور.

الخطوة 3: تهجير إعدادات ESLint الخاصة بك

هذه هي الميزة الأبرز. يقرأ Biome إعدادات ESLint الحالية ويعيد كتابة biome.json بقواعد Biome المكافئة — ويخبرك بنسبة التغطية:

npx biome migrate eslint --write

i 4 ESLint rules found
  - 4 have been migrated to Biome's rules
  - 100% (4) of your ESLint rules are fully covered by Biome
    - 100% (4) via direct migration to Biome rules
- biome.json: configuration successfully migrated.

افتح biome.json وسترى أن كتلة linter تعكس الآن قواعد ESLint الأربعة الخاصة بك تمامًا:

"linter": {
  "enabled": true,
  "rules": {
    "preset": "none",
    "correctness": { "noUnusedVariables": "error" },
    "style": { "useConst": "error" },
    "suspicious": { "noConsole": "warn", "noDoubleEquals": "error" }
  }
}

هناك شيئان يجب فهمهما هنا. أولاً، التعيين (mapping): أصبح no-unused-vars هو noUnusedVariables، وأصبح prefer-const هو useConst، وأصبح eqeqeq هو noDoubleEquals، وحافظ no-console على شدة warn الخاصة به. ثانيًا — وهذا يفاجئ الناس — قام التهجير بضبط "preset": "none". إنه يعيد إنتاج القواعد التي كانت لديك في ESLint فقط، بدلاً من وضع مجموعة قواعد Biome الموصى بها فوقها، حتى لا يتغير سلوك فحص الأخطاء بصمت. إذا كنت تريد قواعد Biome الموصى بها أيضًا، فقم بتغيير none مرة أخرى إلى recommended بعد التهجير.

الخطوة 4: تهجير إعدادات Prettier الخاصة بك

نفس الفكرة بالنسبة للتنسيق. يقوم Biome بتعيين .prettierrc و .prettierignore في نفس ملف biome.json:

npx biome migrate prettier --write

.prettierignore has been successfully migrated.
.prettierrc has been successfully migrated.
- biome.json: configuration successfully migrated.

تستقر إعدادات Prettier الخاصة بك في كتلتي formatter و JavaScript.formatter، ويتحول ملف .prettierignore إلى أنماط مستبعدة (negated globs) في formatter.includes. إليك الحقول المشتقة من Prettier (يكتب Biome أيضًا إعدادات المنسق الافتراضية الخاصة به، مثل bracketSpacing و attributePosition، والتي تم حذفها هنا للإيجاز):

"formatter": {
  "enabled": true,
  "indentStyle": "space",
  "indentWidth": 2,
  "lineWidth": 100,
  "lineEnding": "lf",
  "includes": ["**", "!**/dist", "!**/coverage"]
},
"JavaScript": {
  "formatter": {
    "quoteStyle": "single",
    "semicolons": "asNeeded",
    "trailingCommas": "all"
  }
}

تم التعيين بوضوح: singleQuote: true ← quoteStyle: "single"، و semi: false ← semicolons: "asNeeded"، و trailingComma: "all" ← trailingCommas: "all"، و tabWidth: 2 ← indentWidth: 2، و printWidth: 100 ← lineWidth: 100. يحمل ملف إعداد واحد الآن كل ما كان يستخدمه ESLint و Prettier.

الخطوة 5: قم بتشغيل الفحص الأول، ثم الإصلاح التلقائي

يقوم الأمر biome check بتشغيل المنسق (formatter)، والمدقق (linter)، وفرز الاستيرادات (import sorting) معاً. مخرجاته الافتراضية تطبع إطار الكود كاملاً والإصلاح المقترح لكل مشكلة؛ أضف --reporter=concise للحصول على ملخص سطر واحد لكل مشكلة. قم بتشغيله ضد الملف غير المنظم:

npx biome check --reporter=concise ./src

! src/total.js:11:9: lint/suspicious/noConsole: Don't use console.
× src/total.js:10:18: lint/suspicious/noDoubleEquals: Using == may be unsafe if you are relying on type coercion.
× src/total.js:17:1: assist/source/organizeImports: Sort the exported names.
× src/total.js:1:1: lint/style/useConst: This let declares a variable that is only assigned once.
× src/total.js:3:7: lint/correctness/noUnusedVariables: This variable unusedTotal is unused.
× src/total.js: format: Formatter would have printed the following content:
Checked 1 file in 2ms. No fixes applied.
Found 5 errors.
Found 1 warning.

ينتهي الأمر برمز خروج غير صفري (1) بسبب العثور على مشكلات. كل سطر مميز بعلامة × يمثل خطأ — وهناك خمسة أخطاء، باحتساب اختلاف التنسيق — بينما noConsole، المميز بعلامة !، هو تحذير. الآن قم بتطبيق الإصلاحات الآمنة — وهي الإصلاحات التي يمكن لـ Biome القيام بها دون أي خطر من تغيير السلوك:

npx biome check --write ./src

بعد ذلك، تمت إعادة تنسيق src/total.js، وتحول let label إلى const label (لأنه تم تعيينه مرة واحدة فقط)، وتم فرز أسماء التصدير (export names). لاحظ أن let sum ظل كما هو let لأنه يتم إعادة تعيينه داخل الحلقة — قاعدة useConst في Biome دقيقة وليست عشوائية:

const label = 'cart'
const taxRate = 0.2
const unusedTotal = 0

function total(items, applyTax) {
  let sum = 0
  for (const i of items) {
    sum = sum + i.price
  }
  if (applyTax == true) {
    console.log('applying tax')
    sum = sum * (1 + taxRate)
  }
  return sum
}

export { label, total }

تبقت مشكلتان عن قصد: == والمتغير غير المستخدم unusedTotal. يصنف Biome إصلاحاتهما على أنها غير آمنة، لأن إزالة console.log، أو استبدال == بـ ===، أو إعادة تسمية متغير غير مستخدم يمكن أن يغير سلوك البرنامج أثناء التشغيل. قم بتطبيقها صراحةً باستخدام --unsafe:

npx biome check --write --unsafe ./src

Checked 1 file in 1.9ms. Fixed 1 file.

الآن تحول applyTax == true إلى applyTax === true، وتمت إزالة سطر console.log، وتمت إعادة تسمية unusedTotal غير المستخدم إلى _unusedTotal (يقوم إصلاح Biome غير الآمن بإضافة بادئة بدلاً من الحذف، حتى لا تفقد التصريح بالمتغير بصمت). ينتهي الأمر برمز الخروج 0. التقسيم بين الإصلاحات الآمنة وغير الآمنة هو أهم عادة يجب تعلمها: قم بتشغيل --write في خطافات ما قبل الإرسال (pre-commit hooks)، واحتفظ بـ --write --unsafe لعمليات التنظيف المتعمدة والمراجعة.

الخطوة 6: إضافة سكربتات npm ومحرر الكود الخاص بك

قم بربط Biome في ملف package.json حتى يقوم الفريق بأكمله بتشغيل نفس الأوامر:

"scripts": {
  "lint": "biome lint ./src",
  "format": "biome format --write ./src",
  "check": "biome check --write ./src",
  "ci": "biome ci ./src"
}

يقوم biome lint بتشغيل المدقق فقط، ويقوم biome format --write بتشغيل المنسق فقط، بينما يقوم biome check بكليهما بالإضافة إلى فرز الاستيرادات. للحصول على ملاحظات فورية أثناء الكتابة، قم بتثبيت إضافة Biome الرسمية للمحرر (VS Code أو Zed أو JetBrains) واجعل Biome هو المنسق الافتراضي؛ تستخدم الإضافة نفس ملف biome.json، لذا لن يختلف المحرر وواجهة السطر البرمجي (CLI) أبداً.¹

الخطوة 7: حماية CI باستخدام biome ci

biome ci هو أمر مخصص لخطوط الأنابيب (pipelines) لا يقوم بالكتابة أبداً: فهو يتحقق من التنسيق، والتدقيق، وترتيب الاستيرادات، وينتهي برمز غير صفري إذا كان هناك أي خطأ. في حالة الكود النظيف، ينجح الأمر:

npx biome ci ./src

Checked 1 file in 1.2ms. No fixes applied.

رمز الخروج هو 0. أدخل ملفاً واحداً بتنسيق سيء وسيفشل البناء:

Checked 2 files in 1.2ms. No fixes applied.
Found 2 errors.

رمز الخروج هو 1. ضع ذلك في خطوة GitHub Actions وسيقوم خط الأنابيب الخاص بك بحظر الكود غير المنسق أو الذي يفشل في التدقيق:

- name: Biome
  run: npx biome ci ./src

إذا كنت تقوم بالفعل بنشر سحابي بدون مفاتيح من Actions، فإن هذا يوضع بجانبها — راجع دليل GitHub Actions OIDC للنشر بدون مفاتيح لمعرفة سير العمل المحيط. بالنسبة للمستودعات الضخمة (monorepos)، فإن مخرجات --reporter=concise الجديدة تبقي السجلات قصيرة.⁴

الخطوة 8: جعل Biome يحترم ملف .gitignore

"vcs": {
  "enabled": true,
  "clientKind": "git",
  "useIgnoreFile": true
}

مع ضبط هذا الإعداد ووجود ملف .gitignore يسرد src/generated.js، سيقوم التشغيل فقط بفحص المصدر الحقيقي الخاص بك:

npx biome check ./src

Checked 1 file in 1.1ms. No fixes applied.

تم فحص ملف واحد فقط — تم تخطي الملف الذي تم إنشاؤه تلقائياً. بدءاً من الإصدار v2.5، يحترم Biome أيضاً .git/info/exclude بنفس الطريقة التي يحترم بها .gitignore.⁴

التحقق

تكون قد انتهيت عندما ينجح الكود النظيف في كلا الأمرين مع رمز خروج 0:

npx biome check ./src   # exit 0, "No fixes applied."
npx biome ci ./src      # exit 0
echo $?                 # prints 0

عند هذه النقطة، يمكنك حذف .eslintrc.json، و .prettierrc، و .prettierignore، وإلغاء تثبيت eslint، و prettier، وإضافاتهما. ملف ثنائي واحد، إعداد واحد، وتمريرة واحدة.

الأخطاء الشائعة

أمر migrate eslint يعطي خطأ Cannot find package '@eslint/js'. إذا كان إعداد ESLint الخاص بك يستخدم extends: ["eslint:recommended"] (أو أي إعداد مشترك/إضافة)، فإن Biome يحمله عبر Node لحل تلك المراجع، وهو ما يفشل إذا كنت قد قمت بالفعل بإزالة ESLint. الحل هو الترتيب: قم بالهجرة قبل إلغاء تثبيت ESLint. مع بقاء ESLint مثبتاً حتى يتمكن من توسيع eslint:recommended، سيجد نفس الأمر حوالي 67 قاعدة ESLint، ويهاجر 61 منها، ويبلغ عن تغطية تقارب 92%. هاجر أولاً، تحقق، ثم أزل ESLint.

لم يتم وضع علامة على import غير مستخدم بعد الهجرة. قاعدة no-unused-vars في ESLint تقابل noUnusedVariables في Biome، والتي تغطي المتغيرات — وليس الاستيرادات. يقسم Biome الاستيرادات غير المستخدمة إلى قاعدة منفصلة، وهي noUnusedImports. إذا كنت تعتمد على no-unused-vars لالتقاط الاستيرادات الميتة، فأضف "correctness": { "noUnusedImports": "error" } إلى قواعد المدقق الخاص بك بعد الهجرة.

لقد فقدت قواعد Biome الموصى بها. المتوقع: يقوم migrate eslint بضبط "preset": "none" بحيث يعيد إنتاج قواعد ESLint الخاصة بك فقط. للحصول على مجموعة قواعد Biome الموصى بها أيضاً، قم بتغييرها إلى "preset": "recommended" وأعد تشغيل biome check لرؤية التشخيصات الجديدة.

إعدادات زميل في الفريق تستخدم "recommended": true. هذا المفتاح مهجور اعتباراً من v2.5 لصالح preset. لا يزال يعمل اليوم، ولكن قم بتشغيل biome migrate --write لتحديثه قبل إزالته في إصدار رئيسي مستقبلي.⁴

خيار --write لم يصلح كل شيء. هذا مقصود. يقوم Biome فقط بتطبيق الإصلاحات الآمنة تلقائياً باستخدام --write؛ أما الإصلاحات التي تغير السلوك (المساواة غير الصارمة، استدعاءات console الميتة، الارتباطات غير المستخدمة) تتطلب --write --unsafe. راجع تلك الفروقات بدلاً من تشغيل --unsafe بشكل أعمى في خطاف (hook).

الخطوات التالية ومزيد من القراءة

يتماشى Biome بشكل طبيعي مع بقية أدوات التطوير الحديثة: إذا كنت تسعى بالفعل لزيادة سرعة البناء، فإن مترجم TypeScript الأصلي (tsgo) هو الخطوة المصاحبة لفحص الأنواع، كما أن مراجعة أنماط JavaScript الحديثة تجعل مخرجات قواعد Biome أسهل في القراءة. من هنا، استكشف نظام إضافات GritQL في Biome لكتابة قواعد خاصة بالمشروع، وقم بتفعيل قواعد التدقيق المدركة للأنواع عبر النطاقات، وقم بتشغيل --watch للحصول على تشخيصات حية أثناء البرمجة.⁴

Footnotes

1. Biome — البداية والصفحة الرئيسية. https://biomejs.dev/guides/getting-started/ ↩ ↩² ↩³

2. Biome — "خارطة الطريق لعام 2025 و Biome 2.0" (linting مدرك للأنواع بدون مترجم TypeScript؛ الإضافات؛ النطاقات؛ تحليل الملفات المتعددة). https://biomejs.dev/blog/roadmap-2025/ ↩ ↩²

3. Biome — ادعاءات أداة التنسيق في الصفحة الرئيسية: توافق بنسبة 97% مع Prettier وأسرع بحوالي 35 مرة من Prettier (الاختبار المرجعي: 171,127 سطرًا عبر 2,104 ملفًا، معالج Intel Core i7 1270P). https://biomejs.dev/ ↩

4. Biome — "Biome v2.5 — 500 قاعدة Lint، إصلاح كود الإضافات، و Linting عبر الملفات" (5 يونيو 2026): أكثر من 500 قاعدة، تم إيقاف recommended لصالح preset، دعم --watch، تقارير موجزة، دعم .git/info/exclude، ودعم .svg. https://biomejs.dev/blog/biome-v2-5/ ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷