ESLint

يوفر Next.js تجربة متكاملة مع ESLint جاهزة للاستخدام مباشرة. أضف next lint كسكريبت في ملف package.json:

package.json

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

ثم قم بتشغيل npm run lint أو yarn lint:

Terminal

yarn lint

إذا لم يكن ESLint مضبوطًا مسبقًا في تطبيقك، سيتم توجيهك خلال عملية التثبيت والضبط.

Terminal

yarn lint

سترى رسالة مثل:

? كيف تريد ضبط ESLint؟

❯ صارم (موصى به)
أساسي
إلغاء

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

صارم: يتضمن إعدادات ESLint الأساسية لـ Next.js مع مجموعة قواعد أكثر صرامة لـ Core Web Vitals. هذا هو الإعداد الموصى به للمطورين الذين يقومون بإعداد ESLint لأول مرة.
.eslintrc.json
```
{
  "extends": "next/core-web-vitals"
}
```
أساسي: يتضمن إعدادات ESLint الأساسية لـ Next.js.
.eslintrc.json
```
{
  "extends": "next"
}
```
إلغاء: لا يتضمن أي إعدادات لـ ESLint. اختر هذا الخيار فقط إذا كنت تخطط لإعداد إعدادات ESLint مخصصة بنفسك.

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

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

إذا كنت لا تريد أن يعمل ESLint أثناء next build، راجع وثائق تجاهل ESLint.

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

ضبط ESLint

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

إذا كنت ترغب في استخدام eslint-config-next مع إعدادات ESLint أخرى، راجع قسم الإعدادات الإضافية لمعرفة كيفية القيام بذلك دون حدوث تعارضات.

يتم استخدام مجموعات القواعد الموصى بها من الإضافات التالية لـ ESLint ضمن eslint-config-next:

هذا سيتفوق على الإعدادات من next.config.js.

إضافة ESLint

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

مفعل في الإعداد الموصى به

	القاعدة	الوصف
	@next/next/google-font-display	فرض سلوك font-display مع خطوط جوجل.
	@next/next/google-font-preconnect	التأكد من استخدام `preconnect` مع خطوط جوجل.
	@next/next/inline-script-id	فرض وجود سمة `id` على مكونات `next/script` مع محتوى مضمن.
	@next/next/next-script-for-ga	تفضيل مكون `next/script` عند استخدام السكريبت المضمن لتحليلات جوجل.
	@next/next/no-assign-module-variable	منع تعيين قيمة للمتغير `module`.
	@next/next/no-async-client-component	منع أن تكون مكونات العميل دوال غير متزامنة.
	@next/next/no-before-interactive-script-outside-document	منع استخدام إستراتيجية `beforeInteractive` لـ `next/script` خارج `pages/_document.js`.
	@next/next/no-css-tags	منع استخدام علامات أنماط CSS يدوية.
	@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>`.
	@next/next/no-head-import-in-document	منع استخدام `next/head` في `pages/_document.js`.
	@next/next/no-html-link-for-pages	منع استخدام عناصر `<a>` للتنقل بين صفحات Next.js الداخلية.
	@next/next/no-img-element	منع استخدام عنصر `<img>` بسبب بطء LCP وزيادة استهلاك النطاق الترددي.
	@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	منع السكربتات المتزامنة.
	@next/next/no-title-in-document-head	منع استخدام `<title>` مع مكون `Head` من `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 غير مثبت في الجذر (مثل monorepo)، يمكنك إخبار eslint-plugin-next عن مكان تطبيق Next.js باستخدام خاصية settings في ملف .eslintrc:

.eslintrc.json

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

rootDir يمكن أن يكون مسارًا (نسبي أو مطلق)، نمط (مثل "packages/*/")، أو مصفوفة من المسارات و/أو الأنماط.

فحص المجلدات والملفات المخصصة

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

next.config.js

module.exports = {
  eslint: {
    dirs: ['pages', 'utils'], // تشغيل ESLint فقط على مجلدات 'pages' و 'utils' أثناء عمليات البناء الإنتاجية (next build)
  },
}

بالمثل، يمكن استخدام أعلام --dir و --file مع next lint لفحص مجلدات وملفات محددة:

Terminal

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

التخزين المؤقت

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

Terminal

next lint --no-cache

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

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

.eslintrc.json

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

Core Web Vitals

مجموعة قواعد next/core-web-vitals يتم تفعيلها عند تشغيل next lint لأول مرة واختيار الخيار صارم.

.eslintrc.json

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

next/core-web-vitals يقوم بتحديث eslint-plugin-next ليعتبر بعض القواعد التي تكون تحذيرات افتراضيًا أخطاء إذا كانت تؤثر على Core Web Vitals.

يتم تضمين نقطة الدخول next/core-web-vitals تلقائيًا للتطبيقات الجديدة المنشأة باستخدام Create Next App.

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

Prettier

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

أولاً، قم بتثبيت التبعية:

Terminal

npm install --save-dev eslint-config-prettier

yarn add --dev eslint-config-prettier

pnpm add --save-dev eslint-config-prettier

bun add --dev eslint-config-prettier

ثم أضف prettier إلى ضبط ESLint الحالي:

.eslintrc.json

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

lint-staged

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

.lintstagedrc.js

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],
}

ترحيل الإعدادات الحالية

مجموعة قواعد الإضافة الموصى بها

إذا كان ESLint مضبوطًا مسبقًا في تطبيقك وأي من الشروط التالية صحيحة:

لديك واحدة أو أكثر من الإضافات التالية مثبتة مسبقًا (إما بشكل منفصل أو من خلال ضبط آخر مثل airbnb أو react-app):
- react
- react-hooks
- jsx-a11y
- import
لديك parserOptions محددة تختلف عن كيفية ضبط Babel في Next.js (هذا غير موصى به إلا إذا كنت قد خصصت ضبط Babel)
لديك eslint-plugin-import مثبت مع Node.js و/أو TypeScript resolvers محددة للتعامل مع الاستيرادات

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

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

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

Terminal

npm install --save-dev @next/eslint-plugin-next

yarn add --dev @next/eslint-plugin-next

pnpm add --save-dev @next/eslint-plugin-next

bun add --dev @next/eslint-plugin-next

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

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

إذا كنت تستخدم بالفعل تكوين ESLint منفصلًا وتريد تضمين eslint-config-next، تأكد من توسيعه أخيرًا بعد التكوينات الأخرى. على سبيل المثال:

.eslintrc.json

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

يتولى تكوين next بالفعل تعيين القيم الافتراضية لخصائص parser و plugins و settings. ليست هناك حاجة لإعادة تعريف أي من هذه الخصائص يدويًا إلا إذا كنت بحاجة إلى تكوين مختلف لاستخدامك الخاص.

إذا قمت بتضمين أي تكوينات قابلة للمشاركة أخرى، فسوف تحتاج إلى التأكد من عدم استبدال أو تعديل هذه الخصائص. وإلا، نوصي بإزالة أي تكوينات تشترك في السلوك مع تكوين next أو التوسع مباشرة من إضافة ESLint لـ Next.js كما ذكر أعلاه.

On this page