الفرق بين المراجعتين لصفحة: «Next.js/eslint»

من موسوعة حسوب
→ التعديل السابقالتعديل اللاحق ←
مرئينص الويكي
لا ملخص تعديل
ط مراجعة وتدقيق
سطر 1: سطر 1:
<noinclude>{{DISPLAYTITLE:استخدام مدقق الشيفرة ESLint في Next.js}}</noinclude>
<noinclude>{{DISPLAYTITLE:استخدام مدقق الشيفرة ESLint في Next.js}}</noinclude>
دُعِّمت النسخة 11.0.0 وما بعدها من Next.js بمدقق القواعد ESLint، ولاستخدامه أضف الشيفرة التالية إلى الملف <code>package.json</code>:<syntaxhighlight lang="json">
توفر Next.js دعمًا داخليًا لمدقق القواعد [https://eslint.org/ ESLint]، ولاستخدامه أضف الشيفرة التالية إلى الملف <code>package.json</code> إن لم تكن موجودة إذ تضاف عادة عند إنشاء مشروع Next.js جديد:<syntaxhighlight lang="json">
"scripts": {
"scripts": {
   "lint": "next lint"
   "lint": "next lint"
سطر 6: سطر 6:
</syntaxhighlight>نفِّذ بعد ذلك أحد الأمرين <code>npm run lint</code> أو <code>yarn lint</code>:<syntaxhighlight lang="bash">
</syntaxhighlight>نفِّذ بعد ذلك أحد الأمرين <code>npm run lint</code> أو <code>yarn lint</code>:<syntaxhighlight lang="bash">
yarn lint
yarn lint
</syntaxhighlight>لم يهيأ ESLint بعد في تطبيقك، لذلك سنقودك خلال عمليتي التثبيت والتهيئة:<syntaxhighlight lang="bash">
</syntaxhighlight>إن لم يوجد ملف ضبط ESLint بعد في تطبيقك، فيسظهر لك اقتراح بإضافته مع بعض الخيارات مثل:<syntaxhighlight lang="bash">
yarn lint
yarn lint


سطر 18: سطر 18:
</syntaxhighlight>يمكن اختيار أحد الخيارت الثلاث التالية:
</syntaxhighlight>يمكن اختيار أحد الخيارت الثلاث التالية:


* '''Strict''': (مقيّد) يتضمن قواعد تهيئة الأساسية الخاصة بلغة Next.js بالإضافة إلى مجموعة قواعد مؤشرات ويب الحيوية Core Web Vitals rule-set الأكثر صرامة.
* '''Strict''': (مقيّد) يتضمن قواعد التهيئة الأساسية الخاصة بلغة Next.js بالإضافة إلى مجموعة قواعد مؤشرات ويب الحيوية Core Web Vitals rule-set الأكثر صرامة.
<syntaxhighlight lang="json">
<syntaxhighlight lang="json">
{
{
سطر 29: سطر 29:
</syntaxhighlight>
</syntaxhighlight>


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


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


يمكنك الآن تنفيذ الأمر <code>next lint</code> في كل مرة تريد فيها تشغيل المدقق ليتفحص الأخطاء في الشيفرة. كما سيعمل المدقق تلقائيًا بعد تثبيته عند كل بناءٍ للتطبيق (<code>next build</code>)، وستوقف الأخطاء Errors عملية البناء بينما لن توقفها التنبيهات Warnings. <blockquote>'''ملاحظة''': إن لم ترد تشغيل المدقق تلقائيًا أثناء بناء التطبيق، راجع فقرة تجاهل المدقق ESLint في [[Next.js/next.config.js|توثيق ملف تهيئة Next.js]]</blockquote>'''نصيحة''': استخدم أداة تتكامل مع Next.js لعرض التنبيهات والأخطاء مباشرة في محرر الشيفرة أثناء التطوير.
يمكنك الآن تنفيذ الأمر <code>next lint</code> في كل مرة تريد فيها تشغيل المدقق ليتفحص الأخطاء في الشيفرة. كما سيعمل المدقق تلقائيًا بعد تثبيته عند كل بناءٍ للتطبيق (عبر السكربت <code>next build</code>)، وستوقف الأخطاء Errors عملية البناء بينما لن توقفها التنبيهات Warnings. <blockquote>'''ملاحظة''': إن لم ترد تشغيل المدقق تلقائيًا أثناء بناء التطبيق، راجع فقرة تجاهل المدقق ESLint في [[Next.js/next.config.js|توثيق ملف تهيئة Next.js]].</blockquote>'''نصيحة''': استخدم ضبطًا يتكامل مع المحرر الذي تستعمله لعرض التنبيهات والأخطاء مباشرة في محرر الشيفرة أثناء التطوير، فانظر صفحة [https://eslint.org/docs/latest/user-guide/integrations#editors integrations] واختر المحرر الذي تستعمله واتبع تعليمات الضبط.


== تهيئة المدقق ESLint ليعمل في Next.js ==
== تهيئة المدقق ESLint ليعمل في Next.js ==
تتضمن التهيئة الافتراضية للمدقق (<code>next lint</code>) كل ما تحتاجه لأفضل تجربة تدقيق في Next.js. فإن لم تهيئ بعد ESLint في تطبيقك، ننصحك بتنفيذ الأمر <code>next lint</code> لتثبيته مع خيار التهيئة هذا.<blockquote>'''ملاحظة''': إن أردت استخدام الخيار <code>eslint-config-next</code> مع قواعد تهيئة أخرى، انتقل إلى الفقرة الأخيرة من هذه الصفحة.</blockquote>تُستخدم قواعد التدقيق التالية ضمن خيار التهيئة الافتراضي <code>next lint</code>:
تتضمن التهيئة الافتراضية للمدقق (اعتمادية <code>eslint-config-next</code>) كل ما تحتاجه لأفضل تجربة تدقيق في Next.js. فإن لم تهيئ بعد ESLint في تطبيقك، ننصحك بتنفيذ الأمر <code>next lint</code> وتهيئته.<blockquote>'''ملاحظة''': إن أردت استخدام ضبط <code>eslint-config-next</code> مع قواعد تهيئة أخرى، انتقل إلى الفقرة الأخيرة من هذه الصفحة.</blockquote>تُستخدم قواعد التدقيق التالية ضمن خيار التهيئة الافتراضي <code>next lint</code>:


* <code>[https://www.npmjs.com/package/eslint-plugin-react eslint-plugin-react]</code>
* <code>[https://www.npmjs.com/package/eslint-plugin-react eslint-plugin-react]</code>
سطر 45: سطر 45:


== إضافات ESLint ==
== إضافات ESLint ==
توفّر Next.js إضافات لدعم هذا المدقق (<code>eslint-plugin-next</code>) مجمّعة مسبقًَا ضمن قواعد التهيئة الأساسية التي تمكّن من كشف الأخطاء الأكثر شيوعًا والمشاكل في تطبيقات Next.js. إليك قائمة كاملة بمجموعات القواعد:
توفّر Next.js إضافات لدعم المدقق ESLint، مثل <code>eslint-plugin-next</code>، مجمّعة مسبقًَا ضمن قواعد التهيئة الأساسية التي تمكّن من كشف الأخطاء الأكثر شيوعًا والمشاكل في تطبيقات Next.js. إليك قائمة كاملة بمجموعات القواعد:<blockquote>✔️ تعني مفعّلة في التهيئة المستحسنة.</blockquote>
{| class="wikitable"
{| class="wikitable"
|+
!القاعدة
!القاعدة
!الوصف
!الوصف
!مفعّلة في التهيئة المستحسنة
!
|-
|-
|next/google-font-display
|‎@next/next/google-font-display
|تفرض إحدى القيمتين <code>optional</code> أو <code>swap</code> للخاصية <code>font-display</code> عند استخدام خطوط Goggle
|تفرض السلوك المعتمد للخاصية font-display مع خطوط Google.
|✔️
|✔️
|-
|-
|next/google-font-preconnect
|‎@next/next/google-font-preconnect
|تجبر على استخدام الاتصال المسبق (<code>preconnect</code>) بنطاق خطوط Google عند استخدام هذه الخطوط (لتسريع تحميل الخطوط)
|تجبر على استخدام الاتصال المسبق (preconnect) بنطاق خطوط Google عند استخدام هذه الخطوط (لتسريع تحميل الخطوط).
|✔️
|✔️
|-
|-
|next/link-passhref
|‎@next/next/inline-script-id
|تجبر على استخدام الخاصية <code>passhref</code> مع مكوّن روابط مخصص
|تفرض إضافة الخاصية id مع مكونات next/script ذات المحتوى الضمني السطري inline.
|✔️
|✔️
|-
|-
|next/no-css-tags
|‎@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/no-document-import-in-page
|‎@next/next/no-document-import-in-page
|لا يسمح بإدراج المستند next/document خارج الملف pages/document.js
|لا يسمح بإدراج المكون next/document خارج الملف pages/document.js
|✔️
|✔️
|-
|-
|next/no-head-import-in-document
|‎@next/next/no-duplicate-head
|لا يسمح بإدراج الترويسة next/head في الملف pages/document.js
|تمنع تكرار استخدام المكون <Head> داخل الملف pages/_document.js.
|✔️
|✔️
|-
|-
|next/no-html-link-for-pages
|‎@next/next/no-head-element
|يمنع مرابط HTML بالاتصال بصفحات لا تحتوى مكوّن الروابط
|يمنع استخدام العنصر <head> (عنصر الترويسة في HTML)
|✔️
|✔️
|-
|-
|next/no-img-element
|‎@next/next/no-head-import-in-document
|يمنع استخدام العنصر <code><img></code> (عنصر الصورة في HTML)
|لا يسمح بإدراج الترويسة next/head في الملف pages/document.js.
|✔️
|✔️
|-
|-
|next/no-head-element
|‎@next/next/no-html-link-for-pages
|يمنع استخدام العنصر <code><head></code> (عنصر الترويسة في HTML)
|يمنع استخدام عناصر <a> من HTML مباشرة للانتقال إلى صفحات Next.js الداخلية.
|✔️
|✔️
|-
|-
|next/no-page-custom-font
|‎@next/next/no-img-element
|يمنع استخدام الخطوط المخصصة ضمن صفحة واحدة فقط من التطبيق
|يمنع استخدام العنصر <img> (عنصر الصورة في HTML).
|✔️
|✔️
|-
|-
|next/no-sync-scripts
|‎@next/next/no-page-custom-font
|يمنع السكربتات المتزامنة
|يمنع استخدام الخطوط المخصصة ضمن صفحة واحدة فقط من التطبيق.
|✔️
|✔️
|-
|-
|next/no-title-in-document-head
|‎@next/next/no-script-component-in-head
|تمنع استخدام العنصر <code><title></code> ضمن ترويسة المستند next/document
|يمنع استخدام المكون next/script داخل المكون next/head.
|✔️
|✔️
|-
|-
|next/no-unwanted-polyfillio
|‎@next/next/no-styled-jsx-in-document
|تمنع تكرار شيفرات الموائمة polyfills من Polyfill.io
|يمنع استخدام صياغة styled-jsx داخل pages/_document.js.
|✔️
|✔️
|-
|-
|next/inline-script-id
|‎@next/next/no-sync-scripts
|تفرض استخدام السمة <code>id</code> في مكوّنات الملف next/script التي تضم محتوىً سطريًا
|يمنع السكربتات المتزامنة synchronous scripts.
|✔️
|✔️
|-
|-
|next/no-typos
|‎@next/next/no-title-in-document-head
|التأكد من عدم وجود أخطاء كتابية عند التصريح عن [[Next.js/data fetching|دالة إحضار البيانات في Next.js]]
|تمنع استخدام العنصر <title> ضمن ترويسة المكون next/document.
|✔️
|✔️
|-
|-
|next/next-script-for-ga
|‎@next/next/no-typos
|استخدم المكوّن <code>Script</code> لتأجيل تحميل السكربت حتى وقت الحاجة.
|التأكد من عدم وجود أخطاء كتابية شائعة عند التصريح عن [[Next.js/data fetching|دالة إحضار البيانات في Next.js]].
|✔️
|-
|‎@next/next/no-unwanted-polyfillio
|تمنع تكرار شيفرات الموائمة polyfills من Polyfill.io.
|✔️
|✔️
|}
|}
سطر 132: سطر 147:
</syntaxhighlight>إن قيمة التوجيه هو مسار (نسبي أو مطلق) و/أو أسماء ملفات تضم محارف مبدلة wildcards (مثل <code>"/*/packages"</code>) أو مصفوفة من المسارات أو/و أسماء ملفات بمحارف مبدلة.  
</syntaxhighlight>إن قيمة التوجيه هو مسار (نسبي أو مطلق) و/أو أسماء ملفات تضم محارف مبدلة wildcards (مثل <code>"/*/packages"</code>) أو مصفوفة من المسارات أو/و أسماء ملفات بمحارف مبدلة.  


== تدقيق مجلدات وملفات مخصصة في Next.js ==
== تدقيق مجلدات وملفات مخصصة ==
تشغل Next.js المدقق ESLint افتراضيًا لكل الملفات الموجودة في المجلدات <code>/pages</code> و <code>/components</code> و <code>/lib</code>. لكن بإمكانك أيضًا تخصيص المجلدات التي تريد باستخدام الخيار <code>dirs</code> عند ضبط الإعداد <code>eslint</code> في ملف التهيئة <code>next.config.js</code> وذلك لمرحلة الإنتاج:<syntaxhighlight lang="javascript">
تشغل Next.js المدقق ESLint افتراضيًا لكل الملفات الموجودة في المجلدات التالية:
 
* <code>/pages</code>
* <code>/components</code>
* <code>/lib</code>
* <code>src/‎</code>
 
لكن بإمكانك أيضًا تخصيص المجلدات التي تريد باستخدام الخيار <code>dirs</code> عند ضبط الإعداد <code>eslint</code> في ملف التهيئة <code>next.config.js</code> وذلك لمرحلة الإنتاج:<syntaxhighlight lang="javascript">
module.exports = {
module.exports = {
   eslint: {
   eslint: {
سطر 144: سطر 166:
</syntaxhighlight>
</syntaxhighlight>


== التخزين المؤقت لبيانات المدقق ESLint في Next.js ==
== التخزين المؤقت لبيانات المدقق ESLint ==
تُخزن المعلومات الناتجة عن استخدام المدقق مؤقتًا لتحسين الأداء ضمن الملف <code>next/cache.</code> أو ضمن [[Next,js/next.config.js|مجلد البناء]] الذي حددته. إن وضعت أية قواعد للمدقق تعتمد على محتويات ملف مصدري واحد أو أكثر وتريد تعطيل التخزين المؤقت، نفِّذ الأمر <code>next lint</code> مستخدمًا الراية <code>no-cache--</code>:<syntaxhighlight lang="bash">
تُخزن المعلومات الناتجة عن استخدام المدقق مؤقتًا لتحسين الأداء ضمن الملف <code>next/cache.</code> أو ضمن [[Next.js/next.config.js#.D8.A5.D8.B9.D8.AF.D8.A7.D8.AF .D9.85.D8.AC.D9.84.D8.AF .D8.A8.D9.86.D8.A7.D8.A1 .D9.85.D8.AE.D8.B5.D8.B5|مجلد البناء]] الذي حددته. إن وضعت أية قواعد للمدقق تعتمد على محتويات ملف مصدري واحد أو أكثر وتريد تعطيل التخزين المؤقت، نفِّذ الأمر <code>next lint</code> مستخدمًا الراية <code>no-cache--</code>:<syntaxhighlight lang="bash">
next lint --no-cache
next lint --no-cache
</syntaxhighlight>
</syntaxhighlight>


== تعطيل قواعد المدقق ESLint في Next.js ==
== تعطيل قواعد المدقق ESLint ==
إن أردت تعديل أو تعطيل أية قواعد مصدرها الإضافات التي تدعمها (مثل <code>react</code> أو <code>react-hooks</code> أو <code>next</code>)، بإمكانك تغيير هذه القواعد مباشرة باستخدام الخاصية <code>rules</code> في الملف <code>eslintrc.</code>:<syntaxhighlight lang="json">
إن أردت تعديل أو تعطيل أية قواعد مصدرها الإضافات التي تدعمها (مثل <code>react</code> أو <code>react-hooks</code> أو <code>next</code>)، بإمكانك تغيير هذه القواعد مباشرة باستخدام الخاصية <code>rules</code> في الملف <code>eslintrc.</code>:<syntaxhighlight lang="json">
{
{
سطر 167: سطر 189:
</syntaxhighlight>تغيّر مجموعة القواعد <code>next/core-web-vitals</code> بعض قواعد الإضافة <code>eslint-plugin-next</code> التي تعطي التنبيهات افتراضيًا كي تعطي أخطاءً بدلًا منها إن أثّرت على مؤشرات ويب الحيوية.<blockquote>'''ملاحظة''': يُهيئ مدخل تنفيذ <code>next/core-web-vitals</code> تلقائيًا في التطبيقات المبنية باستخدام [[Next.js/create next app|Create Next App]].</blockquote>
</syntaxhighlight>تغيّر مجموعة القواعد <code>next/core-web-vitals</code> بعض قواعد الإضافة <code>eslint-plugin-next</code> التي تعطي التنبيهات افتراضيًا كي تعطي أخطاءً بدلًا منها إن أثّرت على مؤشرات ويب الحيوية.<blockquote>'''ملاحظة''': يُهيئ مدخل تنفيذ <code>next/core-web-vitals</code> تلقائيًا في التطبيقات المبنية باستخدام [[Next.js/create next app|Create Next App]].</blockquote>


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


=== مع الأداة Prettier ===
=== Prettier ===
يضم المدقق ESLint أيضًا قواعد لتنسيق الشيفرة والتي قد تتعارض مع إعدادات الأداة [https://prettier.io/ Prettier]. ننصحك بتثبيت الإضافة [https://github.com/prettier/eslint-config-prettier eslint-config-prettier] وتضمينها في قواعد تهيئة ESLint ليعمل مع الأداة دون مشاكل.
يضم المدقق ESLint أيضًا قواعد لتنسيق الشيفرة والتي قد تتعارض مع إعدادات الأداة [https://prettier.io/ Prettier]. ننصحك بتثبيت الإضافة [https://github.com/prettier/eslint-config-prettier eslint-config-prettier] وتضمينها في قواعد تهيئة ESLint ليعمل مع الأداة دون مشاكل.


سطر 183: سطر 205:
</syntaxhighlight>
</syntaxhighlight>


=== مع الأداة lint-staged ===
=== lint-staged ===
إن أردت استخدام <code>next lint</code> مع الأداة lint-staged لتدقيق ملفات git المهيأة للشحن، لا بد من إضافة الشيفرة التالية إلى الملف <code>lintstagedrc.js.</code> في المجلد الجذري للمشروع لتحديد استخدام الراية <code>file--</code>:<syntaxhighlight lang="javascript">
إن أردت استخدام <code>next lint</code> مع الأداة [https://github.com/okonet/lint-staged lint-staged] لتدقيق ملفات git المضافة المهيأة للإيداع staged، لا بد من إضافة الشيفرة التالية إلى الملف <code>lintstagedrc.js.</code> في المجلد الجذري للمشروع لتحديد استخدام الراية <code>file--</code>:<syntaxhighlight lang="javascript">
const path = require('path')
const path = require('path')


سطر 200: سطر 222:


=== مجموعة قواعد من إضافات يوصى بها ===
=== مجموعة قواعد من إضافات يوصى بها ===
إن كان ESLint مهيّأً في تطبيقك وتحقق إي شرط من الشروط التالية:
إن كان ESLint مهيّأً في تطبيقك وتحقق أي شرط من الشروط التالية:


* إحدى هذه الإضافات أو أكثر مُثبّتة (منفصلة أو من خلال قواعد تهيئة منفصلة مثل <code>airbnb</code> أو <code>react-app</code>):
* إحدى هذه الإضافات أو أكثر مُثبّتة (منفصلة أو من خلال قواعد تهيئة منفصلة مثل <code>airbnb</code> أو <code>react-app</code>):
سطر 209: سطر 231:
* حددت خيارات مخصصة للمحلل عبر الخاصية <code>parserOptions</code> تختلف عن تهيئة Babel (برنامج لنقل الشيفرة بين إصدارين مختلفين للغة البرمجة) في Next.js (وهذا غير مستحسن إلا إن [[Next.js/customizing babel config|خصصت تهيئة Babel في تطبيقك]])
* حددت خيارات مخصصة للمحلل عبر الخاصية <code>parserOptions</code> تختلف عن تهيئة Babel (برنامج لنقل الشيفرة بين إصدارين مختلفين للغة البرمجة) في Next.js (وهذا غير مستحسن إلا إن [[Next.js/customizing babel config|خصصت تهيئة Babel في تطبيقك]])


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


ننصحك عند ذلك بإزالة هذه الإعدادات إن كنت تفضل القيم الافتراضية التي تضبطها <code>eslint-config-next</code> أو أن تتوسع مباشرة من خلال الإضافة ESLint الخاصة بلغة Next.js:<syntaxhighlight lang="javascript">
ننصحك عند ذلك بإزالة هذه الإعدادات إن كنت تفضل القيم الافتراضية التي تضبطها <code>eslint-config-next</code> أو أن تتوسع مباشرة من خلال الإضافة ESLint الخاصة بلغة Next.js:<syntaxhighlight lang="javascript">
سطر 230: سطر 252:
   "extends": ["eslint:recommended", "next"]
   "extends": ["eslint:recommended", "next"]
}
}
</syntaxhighlight>تتكفل Next.js بضبط القيم الافتراضية للخاصيات <code>parser</code> و <code>plugins</code> و <code>settings</code>، ولا حاجة لإعادة التصريح اليدوي لأي منها إلا إن أردت تهيئة مختلفة تناسب حالة خاصة بك. إن ضمّنت أية إعدادت تهيئة قابلة للمشاركة، فعليك أن تتأكد من عدم تعديل أو إلغاء قيم الخاصيات السابقة. في بقية الحالات ننصحك بإزالة أية قواعد مشتركة مع قواعد تهيئة <code>next</code> أو تتوسع مباشرة عن الإضافة ESLint كما شرحنا سابقًا.
</syntaxhighlight>تتكفل Next.js بضبط القيم الافتراضية للخاصيات <code>parser</code> و <code>plugins</code> و <code>settings</code>، ولا حاجة لإعادة التصريح اليدوي لأي منها إلا إن أردت تهيئة مختلفة تناسب حالة خاصة بك. إن ضمّنت أية إعدادت تهيئة قابلة للمشاركة، فعليك أن تتأكد من '''عدم تعديل أو إلغاء قيم الخاصيات السابقة'''. في بقية الحالات ننصحك بإزالة أية قواعد مشتركة مع قواعد تهيئة <code>next</code> أو تتوسع مباشرة عن الإضافة ESLint كما شرحنا سابقًا.


== المصادر ==
== المصادر ==


* الصفحة [https://nextjs.org/docs/basic-features/eslint ESLint] من توثيق Next.js الرسمي.
* الصفحة [https://nextjs.org/docs/basic-features/eslint ESLint] من توثيق Next.js الرسمي.

مراجعة 15:57، 5 نوفمبر 2022

توفر 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 الرسمي.
مجلوبة من «https://wiki.hsoub.com/index.php?title=Next.js/eslint&oldid=32463»