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.

TypeScript

بالإضافة إلى قواعد ESLint الخاصة بـ Next.js، فإن create-next-app --typescript سيضيف أيضًا قواعد فحص خاصة بـ TypeScript باستخدام next/typescript إلى إعدادك:

.eslintrc.json

{
  "extends": ["next/core-web-vitals", "next/typescript"]
}

هذه القواعد مبنية على plugin:@typescript-eslint/recommended. راجع typescript-eslint > Configs لمزيد من التفاصيل.

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

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 أو التمديد مباشرة من ملحق ESLint الخاص بـ Next.js بدلاً من ذلك:

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