استخدام مدقق الشيفرة ESLint في Next.js

دُعمت النسخة 11.0.0 وما بعدها من Next.js بمدقق القواعد ESLint، ولاستخدامه أضف الشيفرة التالية إلى الملف package.json:

"scripts": {
  "lint": "next lint"
}

نفِّذ بعد ذلك أحد الأمرين npm run lint أو yarn lint:

yarn lint

لم يهيأ ESLint بعد في تطبيقك، لذلك سنقودك خلال عمليتي التثبيت والتهيئة:

yarn lint

# سترى محثًا له الشكل التالي 
#
# ? How would you like to configure ESLint?
#
# ❯   Base configuration + Core Web Vitals rule-set (recommended)
#     Base configuration
#     None

يمكن اختيار أحد الخيارت الثلاث التالية:

Strict: (مقيّد) يتضمن قواعد تهيئة الأساسية الخاصة بلغة Next.js بالإضافة إلى مجموعة قواعد مؤشرات ويب الحيوية Core Web Vitals rule-set الأكثر صرامة.

{
  "extends": "next/core-web-vitals"
}

Base: (أساسي) يتضمن قواعد تهيئة الأساسية الخاصة بلغة Next.js.

{
  "extends": "next"
}

Cancel: لا يتضمن أية قواعد تهيئة. لا تفعّل هذا الخيار إلا إن كنت تخطط لوضع قواعد خاصة بك لتهيئة المدقق ESLint

إن اخترت أحد الخيارين الأول أو الثاني ستثبت المدقق eslint و اعتمادية التطوير eslint-config-next في تطبيقك ، وتنشئ الملف eslintrc.json. الذي يحتوي على قواعد التهيئة المختارة في المجلد الجذري لمشروعك.

يمكنك الآن تنفيذ الأمر next lint في كل مرة تريد فيها تشغيل المدقق ليتفحص الأخطاء في الشيفرة. كما سيعمل المدقق تلقائيًا بعد تثبيته عند كل بناء للتطبيق (next build)، وستوقف الأخطاء Errors عملية البناء بينما لن توقفها التنبيهات Warnings.

إن لم ترد تشغيل المدقق تلقائيًا أثناء بناء التطبيق، راجع فقرة تجاهل المدقق ESLint في توثيق ملف تهيئة Next.js

نصيحة: استخدم أداة تتكامل مع Next.js لعرض التنبيهات و الأخطاء مباشرة في محرر الشيفرة أثناء التطوير.

تهيئة المدقق ESLint ليعمل في Next.js

تتضمن التهيئة الافتراضية للمدقق (next lint) كل ما تحتاجه لأفضل تجربة تدقيق في Next.js. فإن لم تهيئ بعد ESLint في تطبيقك، ننصحك بتنفيذ الأمر next lint لتثبيت مع خيار التهيئة هذا.

إن أردت استخدام الخيار مع قواعد تهيئة أخرى، انتقل إلى الفقرة الأخيرة من هذه الصفحة.

تُستخدم قواعد التدقيق التالية ضمن خيار التهيئة الافتراضي next lint:

يمكنك الاطلاع على تفاصيل قواعد التهيئة القابلة للمشاركة في حزمة eslint-config-next، وسترجح الكفة لهذه القواعد مقارنة بتلك الموجودة في الملف next.config.js.

إضافات ESLint

توفّر Next.js إضافة لدعم هذا المدقق (eslint-plugin-next) مجمّعة مسبقًَا ضمن قواعد التهيئة الأساسية التي تمكّن من كشف الأخطاء الأكثر شيوعًا والمشاكل في تطبيقات Next.js. إليك قائمة كاملة بمجموعات القواعد:


القاعدة	الوصف	مفعّلة في التهيئة المستحسنة
next/google-font-display	تفرض إحدى القيمتين `optional` أو `swap` للخاصية `font-display` عند استخدام خطوط Goggle	✔️
next/google-font-preconnect	تجبر علىاستخدام الاتصال المسبق (`preconnect`) بنطاق خطوط Google عند استخدام هذه الخطوط (لتسريع تحميل الخطوط)	✔️
next/link-passhref	تجبر على استخدام الخاصية `passhref` مع مكوّن روابط مخصص	✔️
next/no-css-tags	يمنع الوسوم اليدوية لصفحات التنسيق	✔️
next/no-document-import-in-page	لا يسمح بإدراج المستند next/document خارج الملف pages/document.js	✔️
next/no-head-import-in-document	لا يسمح بإدراج الترويسة next/head في الملف pages/document.js	✔️
next/no-html-link-for-pages	يمنع مرابط HTML بالاتصال بصفحات لا تحتوى مكوّن الروابط	✔️
next/no-img-element	يمنع استخدام العنصر `<img>` (عنصر الصورة في HTML)	✔️
next/no-head-element	يمنع استخدام العنصر `<head>` (عنصر الترويسة في HTML)	✔️
next/no-page-custom-font	يمنع استخدام الخطوط المخصصة ضمن صفحة واحدة فقط من التطبيق	✔️
next/no-sync-scripts	يمنع السكربتات المتزامنة	✔️
next/no-title-in-document-head	تمنع استخدام العنصر `<title>`ضمن ترويسة المستند next/document	✔️
next/no-unwanted-polyfillio	تمنع تكرار شيفرات الموائمة polyfills من Polyfill.io	✔️
next/inline-script-id	تفرض استخدام السمة `id` في مكوّنات الملف next/script التي تضم محتوىً سطريًا	✔️
next/no-typos	التأكد من عدم وجود أخطاء كتابية عند التصريح عن دالة إحضار البيانات في Next.js	✔️
next/next-script-for-ga	استخدم المكوّن `Script` لتأجيل تحميل السكربت حتى وقت الحاجة.	✔️

إن كنت قد هيأت المدقق ESLint مسبقًا في تطبيقك، ننصحك بتوسيع القواعد انطلاقًا من هذه الإضافات مباشرة بدلًا من تضمين eslint-config-next إلا إن تحققت بعض الشروط التي سنراها لاحقًا في هذه الصفحة.

إعدادات مخصصة

التوجيه rootDir: إن كنت تستخدم الإضافة eslint-plugin-next في مشروع لم تُثبّت فيه Next.js في المجلد الجذري، يمكنك إرشاد الإضافة إلى مكان وجود تطبيق Next.js باستخدام الخاصية settings في ملف قواعد المدقق eslintrc.:

{
  "extends": "next",
  "settings": {
    "next": {
      "rootDir": "packages/my-app/"
    }
  }
}

إن قيمة التوجيه هو مسار (نسبي أو مطلق) وأو أسماء ملفات تضم محارف مبدلة wildcards (مثل "/*/packages") أو مصفوفة من المسارات أو/و أسماء ملفات بمحارف مبدلة.

تدقيق مجلدات و ملفات مخصصة في Next.js

تشغل Next.js المدقق ESLint افتراضيًا لكل الملفات الموجودة في المجلدات /pages و /components و /lib. لكن بإمكانك أيضًا تخصيص المجلدات التي تريد باستخدام الخيار dirs عند ضبط الإعداد eslint في ملف next.config.js التهيئة وذلك لمرحلة الإنتاج:

module.exports = {
  eslint: {
    dirs: ['pages', 'utils'], // utils و pages يُشغّل المدقق فقط للمجلدين 
                              // في مرحلة الإنتاج
   },
}

يمكنك استخدام الرايتين dir-- و file-- مع الأمر next lint لتدقيق مجلدات وملفات محددة:

next lint --dir pages --dir utils --file bar.js

التخزين المؤقت لبيانات المدقق ESLint في Next.js

تُخزن المعلومات الناتجة عن استخدام المدقق مؤقتًا لتحسين الأداء ضمن الملف .next/cache أو ضمن مجلد البناء الذي حددته. إن وضعت أية قواعد للمدقق تعتمد على محتويات ملف مصدري واحد أو أكثر وتريد تعطيل التخزين المؤقت، نفِّذ الأمر next lint مستخدمًا الراية no-cache--:

next lint --no-cache

تعطيل قواعد المدقق ESLint في Next.js

إن أردت تعديل أو تعطيل أية قواعد مصدرها الإضافات التي تدعمها (مثل react أو react-hooks أو next)، بإمكانك تغيير هذه القواعد مباشرة باستخدام الخاصية rules في الملف eslintrc.:

{
  "extends": "next",
  "rules": {
    "react/no-unescaped-entities": "off",
    "@next/next/no-page-custom-font": "off"
  }
}

مؤشرات ويب الحيوية

تُفعّل مجموعة القواعد next/core-web-vitals عند تنفيذ الأمر next lint أول مرة ويُفعّل الخيار strict الذي أشرنا إليه في بداية هذه الصفحة.

{
  "extends": "next/core-web-vitals"
}

تغيّر مجموعة القواعد next/core-web-vitals بعض قواعد الإضافة eslint-plugin-next التي تعطي تنبيهات افتراضيًا لتعطي أخطاءً إن أثّرت على مؤشرات ويب الحيوية.

يُهيئ مدخل تنفيذ next/core-web-vitals تلقائيًا في التطبيقات المبنية باستخدام Create Next App.

استخدامات ESLint مع أدوات أخرى

قد تتعارض بعض قواعد المدقق مع قواعد تضيفها أدوات أخرى، لهذا سنلقي الضوء على بعضها

مع الأداة Prettier

يضم المدقق ESLint أيضًا على قواعد لتنسيق الشيفرة والتي قد تتعارض مع إعدادات الأداة Prettier. ننصحك بتثبيت الإضافة eslint-config-prettier وتضمينها في قواعد تهيئة ESLint ليعمل مع الأداة دون مشاكل.

ثبّت أولًا الاعتمادية:

npm install --save-dev eslint-config-prettier
# أو
yarn add --dev eslint-config-prettier

أضف بعد ذلك القيمة prettier إلى قواعد تهيئة ESLint الموجودة:

{
  "extends": ["next", "prettier"]
}

مع الأداة lint-staged

إن أردت استخدام next lint مع الأداة lint-staged لتدقيق ملفات git المهيأة للشحن، لا بد من إضافة الشيفرة التالية إلى الملف .lintstagedrc.js في المجلد الجذري للمشروع لتحديد استخدام الراية file--:

const path = require('path')

const buildEslintCommand = (filenames) =>
  `next lint --fix --file ${filenames
    .map((f) => path.relative(process.cwd(), f))
    .join(' --file ')}`

module.exports = {
  '*.{js,jsx,ts,tsx}': [buildEslintCommand],
}

ترحيل قواعد التهيئة الموجودة في Next.js

مجموعة قواعد من إضافات يوصى بها

إن كان ESLint مهيّأً في تطبيقك وتحقق إي شرط من الشروط التالية:

إحدى هذه الإضافات أو أكثر مُثبّتة (منفصلة أو من خلال قواعد تهيئة منفصلة مثل airbnb أو react-app):
- react
- react-hooks
- jsx-a11y
- import
حددت خيارات مخصصة للمحلل عبر الخاصية parserOptions تختلف عن تهيئة Babel (برنامج لنقل الشيفرة بين إصدارين مختلفين للغة البرمجة) في (وهذا غير مستحسن إلا إن خصصت تهيئة Babel في تطبيقك)

ثبتَّ الإضافة eslint-plugin-import مع محللات Resolvers للغة Node.js أو/و TypeScript مُعرّفة للتعامل مع عمليات الإدراج imports.

ننصحك عند ذلك بإزالة هذه الإعدادات إن كنت تفضل القيم الافتراضية التي تضبطها eslint-config-next أو أن تتوسع مباشرة من خلال الإضافة ESLint الخاصة بلغة Next.js:

module.exports = {
  extends: [
    //...
    'plugin:@next/next/recommended',
  ],
}

يمكنك تثبيت الإضافة عادة في مشروعك دون الحاجة إلى تنفيذ الأمر next lint:

npm install --save-dev @next/eslint-plugin-next
# أو
yarn add --dev @next/eslint-plugin-next

يزيل ذلك خطر التعارض أو الأخطاء التي قد تحدث نتيجة إدراج نفس الإضافة أو المحلل في الإعدادات المختلفة.

إعدادت إضافية

إن كنت تستخدم إعدادت تهيئة منفصلة للمدقق وأردت تضمين قواعد التهيئة eslint-config-next، تأكد من وجودها بعد آخر توسعة للإعدادات. إليك مثالًا:

{
  "extends": ["eslint:recommended", "next"]
}

تتكفل بضبط القيم الافتراضية للخاصيات parser و plugins و settings، ولا حاجة لإعادة التصريح اليدوي لأي منها إلا إن أردت تهيئة مختلفة تناسب حالة خاصة بك. إن ضمّنت أية إعدادت تهيئة قابلة للمشاركة، فعليك أن تتأكد من عدم تعديل أو إلغاء قيم الخاصيات السابقة. في بقية الحالات ننصحك بإزالة أية قواعد مشتركة مع قواعد تهيئة next أو تتوسع مباشرة عن الإضافة ESLint كما شرحنا سابقًا.