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

توفر Next.js دعمًا داخليًا لمدقق القواعد ESLint، ولاستخدامه أضف الشيفرة التالية إلى الملف package.json إن لم تكن موجودة إذ تضاف عادة عند إنشاء مشروع Next.js جديد:

"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.

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

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

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

نصيحة: استخدم ضبطًا يتكامل مع المحرر الذي تستعمله لعرض التنبيهات والأخطاء مباشرة في محرر الشيفرة أثناء التطوير، فانظر صفحة integrations واختر المحرر الذي تستعمله واتبع تعليمات الضبط.

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

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

ملاحظة: إن أردت استخدام ضبط eslint-config-next مع قواعد تهيئة أخرى، انتقل إلى الفقرة الأخيرة من هذه الصفحة.

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

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

إضافات ESLint

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

✔️ تعني مفعّلة في التهيئة المستحسنة.

القاعدة	الوصف
‎@next/next/google-font-display	تفرض السلوك المعتمد للخاصية font-display مع خطوط Google.	✔️
‎@next/next/google-font-preconnect	تجبر على استخدام الاتصال المسبق (preconnect) بنطاق خطوط Google عند استخدام هذه الخطوط (لتسريع تحميل الخطوط).	✔️
‎@next/next/inline-script-id	تفرض إضافة الخاصية id مع مكونات next/script ذات المحتوى الضمني السطري inline.	✔️
‎@next/next/next-script-for-ga	ترجئ تحميل المكون next/script عند استخدام سكربت مضمن سطري inline script من أجل خدمة تحليلات غوغل Google Analytics.	✔️
‎@next/next/no-assign-module-variable	تمنع أي إسناد إلى المتغير module.	✔️
‎@next/next/no-before-interactive-script-outside-document	تمنع استخدام آلية beforeInteractive مع مكونات next/script خارج الملف pages/_document.js.	✔️
‎@next/next/no-css-tags	يمنع الوسوم اليدوية لصفحات التنسيق	✔️
‎@next/next/no-document-import-in-page	لا يسمح بإدراج المكون next/document خارج الملف pages/document.js	✔️
‎@next/next/no-duplicate-head	تمنع تكرار استخدام المكون <Head> داخل الملف pages/_document.js.	✔️
‎@next/next/no-head-element	يمنع استخدام العنصر <head> (عنصر الترويسة في HTML)	✔️
‎@next/next/no-head-import-in-document	لا يسمح بإدراج الترويسة next/head في الملف pages/document.js.	✔️
‎@next/next/no-html-link-for-pages	يمنع استخدام عناصر <a> من HTML مباشرة للانتقال إلى صفحات Next.js الداخلية.	✔️
‎@next/next/no-img-element	يمنع استخدام العنصر <img> (عنصر الصورة في HTML).	✔️
‎@next/next/no-page-custom-font	يمنع استخدام الخطوط المخصصة ضمن صفحة واحدة فقط من التطبيق.	✔️
‎@next/next/no-script-component-in-head	يمنع استخدام المكون next/script داخل المكون next/head.	✔️
‎@next/next/no-styled-jsx-in-document	يمنع استخدام صياغة styled-jsx داخل pages/_document.js.	✔️
‎@next/next/no-sync-scripts	يمنع السكربتات المتزامنة synchronous scripts.	✔️
‎@next/next/no-title-in-document-head	تمنع استخدام العنصر <title> ضمن ترويسة المكون next/document.	✔️
‎@next/next/no-typos	التأكد من عدم وجود أخطاء كتابية شائعة عند التصريح عن دالة إحضار البيانات في Next.js.	✔️
‎@next/next/no-unwanted-polyfillio	تمنع تكرار شيفرات الموائمة polyfills من Polyfill.io.	✔️

إن كنت قد هيأت المدقق 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 المدقق ESLint افتراضيًا لكل الملفات الموجودة في المجلدات التالية:

/pages
/components
/lib
src/‎

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

next lint --no-cache

تعطيل قواعد المدقق ESLint

إن أردت تعديل أو تعطيل أية قواعد مصدرها الإضافات التي تدعمها (مثل 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 المضافة المهيأة للإيداع staged، لا بد من إضافة الشيفرة التالية إلى الملف 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 (برنامج لنقل الشيفرة بين إصدارين مختلفين للغة البرمجة) في Next.js (وهذا غير مستحسن إلا إن خصصت تهيئة 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"]
}

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

المصادر

الصفحة ESLint من توثيق Next.js الرسمي.