الخطوات
-
1
ثبّت Prettier و ESLint
ثبّت الأدوات الثلاثة كتبعيات تطوير.
@eslint/jsيوفر مجموعة القواعد الموصى بها الحديثة.eslint-config-prettierهو الجسر الذي يمنع تعارضات التنسيق — يوقف جميع قواعد ESLint التي يتولاها Prettier.bashnpm install --save-dev prettier eslint @eslint/js eslint-config-prettier # Confirm installations npx prettier --version npx eslint --version -
2
أنشئ ملف إعداد .prettierrc
أنشئ
.prettierrcفي جذر المشروع. لدى Prettier إعدادات افتراضية معقولة — تحتاج فقط لتجاوز الخيارات التي لا توافق عليها. الثلاثة الأكثر تخصيصاً هيsemiوsingleQuoteوprintWidth.اختر إعداداً وارتكن عليه. الهدف الاتساق لا الكمال. تنسيق الاختيار الثاني للفريق، المُطبَّق تلقائياً، أفضل من أفضل تنسيق يُطبَّق بالضغط الاجتماعي فقط.
json// .prettierrc { "semi": true, "singleQuote": true, "printWidth": 100, "tabWidth": 2, "trailingComma": "all", "arrowParens": "always" } -
3
أنشئ ملف إعداد ESLint الجديد
يستخدم ESLint v9+ ملف إعداد مسطح اسمه
eslint.config.js(الصيغة القديمة.eslintrcمُهمَلة). السطر الأهم هوeslintConfigPrettierفي نهاية المصفوفة — يُعطّل جميع قواعد تنسيق ESLint حتى لا تتعارض مع Prettier.javascript// eslint.config.js import js from '@eslint/js'; import eslintConfigPrettier from 'eslint-config-prettier'; export default [ js.configs.recommended, { rules: { // Your project-specific rules 'no-console': 'warn', 'no-unused-vars': ['error', { argsIgnorePattern: '^_' }], 'no-var': 'error', 'prefer-const': 'error', }, }, // MUST be last — disables ESLint formatting rules // so Prettier can own them without conflicts eslintConfigPrettier, ]; // Note: if your package.json doesn't have "type": "module", // use .mjs extension: eslint.config.mjs -
4
أضف ملفات الاستثناء
أخبر كلتا الأداتين بتخطي الملفات المولّدة والتبعيات. بدون هذه الملفات، يُضيّع Prettier وESLint الوقت في معالجة مئات الملفات التي لا يجب أن يلمساها.
bash# .prettierignore node_modules/ dist/ build/ coverage/ *.min.js package-lock.json pnpm-lock.yaml # Also add ignores to eslint.config.js: # Add this object BEFORE the rules objects: { ignores: [ 'node_modules/', 'dist/', 'build/', 'coverage/', '**/*.min.js', ], } -
5
أضف سكريبتات التنسيق والفحص
أضف سكريبتات إلى
package.jsonحتى يستخدم الفريق بأكمله نفس الأوامر.format:checkيُستخدم في CI لإفشال البناء إن وُجد كود غير منسّق؛formatهو أمر الإصلاح المحلي.javascript// package.json { "scripts": { "lint": "eslint .", "lint:fix": "eslint . --fix", "format": "prettier --write \"**/*.{js,ts,jsx,tsx,json,css,md}\"", "format:check": "prettier --check \"**/*.{js,ts,jsx,tsx,json,css,md}\"" } } // Usage: npm run format # fix all files in place npm run format:check # just check, no writes (good for CI) npm run lint # report ESLint violations npm run lint:fix # auto-fix fixable violations -
6
فعّل Format on Save في VS Code
ثبّت إضافة Prettier - Code formatter (المعرّف:
esbenp.prettier-vscode). ثم اضبط VS Code ليُنسّق عند كل حفظ. ارتكن على ملف الإعدادات حتى يحصل عليه الفريق بأكمله تلقائياً.json// .vscode/settings.json { "editor.defaultFormatter": "esbenp.prettier-vscode", "editor.formatOnSave": true, "editor.codeActionsOnSave": { "source.fixAll.eslint": "explicit" }, // Per-language overrides (if needed) "[javascript]": { "editor.defaultFormatter": "esbenp.prettier-vscode" }, "[typescript]": { "editor.defaultFormatter": "esbenp.prettier-vscode" } } -
7
أضف خطاف pre-commit مع Husky و lint-staged
Format on Save مجاملة للمطور. خطاف pre-commit هو التطبيق الفعلي. يُشغّل Prettier وESLint فقط على الملفات المُهيَّأة للإيداع — سريع ومُستهدف وتلقائي. الكود الذي يفشل الخطاف لا يمكن إيداعه.
bash# Install husky and lint-staged npm install --save-dev husky lint-staged # Initialize husky (creates .husky/ directory) npx husky init # The init command creates .husky/pre-commit — replace its content: echo 'npx lint-staged' > .husky/pre-commit -
8
اضبط lint-staged
أضف إعداد
lint-stagedإلىpackage.json. هذا يُخبر lint-staged بالضبط أي أداة يُشغّل على أي نوع ملف. علامة--fixعلى ESLint تعني أنه يُصحّح تلقائياً ما يستطيع قبل الإيداع؛ Prettier يُعيد كتابة الملف ليطابق إعداد التنسيق.javascript// package.json — add this at the top level { "lint-staged": { "*.{js,ts,jsx,tsx}": [ "prettier --write", "eslint --fix" ], "*.{json,css,md}": [ "prettier --write" ] } } // Test it: stage a file with bad formatting, then commit git add src/index.js git commit -m "test" // Prettier runs on src/index.js, ESLint runs on src/index.js // If either fails (unfixable ESLint error), the commit is blocked
نصائح ومحاذير
- شغّل <code>npm run format</code> مرة واحدة على كامل قاعدة الكود قبل إعداد خطاف pre-commit — وإلا فإن أول إيداع بعد الإعداد سيُعيد كتابة مئات الملفات ويُلوّث سجل git blame.
- ESLint وPrettier يخدمان أغراضاً مختلفة ولا يجب أن يتداخلا. ESLint يرصد <code>no-unused-vars</code> و<code>no-undef</code> و<code>prefer-const</code>. Prettier يتعامل مع المسافات البادئة والاقتباسات وطول السطر. لا تحاول أبداً تطبيق التنسيق عبر قواعد ESLint حين يكون Prettier مثبتاً.
- إن كنت تستخدم TypeScript، ثبّت أيضاً <code>@typescript-eslint/eslint-plugin</code> و<code>@typescript-eslint/parser</code> لقواعد الفحص المدركة للأنواع.
- أضف فحص CI (<code>npm run format:check && npm run lint</code>) إلى سير عمل GitHub Actions. هذا يرصد ما أفلت من خطاف pre-commit (تخُطِّي بـ <code>--no-verify</code>) أو ما عُدِّل مباشرة على البعيد.
- أمر <code>prettier --write</code> يُعدّل الملفات في مكانها. إن أردت معاينة التغييرات دون كتابة، استخدم <code>prettier --check</code> — يخرج بكود غير صفري إن احتاج أي ملف تنسيقاً، وهذا ما يستخدمه CI.
خاتمة
Prettier وESLint معاً يحلان مشكلتين مختلفتين تماماً. Prettier يزيل فئة نقاشات التنسيق بأكملها من فريقك — لا أحد يتجادل حول الفاصلة المنقوطة حين تقرر آلة. ESLint يرصد أنماط الكود التي تهم فعلاً: المتغيرات غير المعرّفة، والاستيرادات غير المستخدمة، والاستخدام غير المتسق لـ const/let. خطاف pre-commit هو طبقة التطبيق التي تعني أن كلتا الأداتين لا تعتمدان على انضباط المطور لتعملا.