Плагин ESLint

Next.js включает плагин ESLint eslint-plugin-next, который входит в базовую конфигурацию и помогает выявлять распространённые проблемы в приложениях Next.js.

Справочник

Рекомендуемые наборы правил из следующих плагинов ESLint используются в eslint-config-next:

• eslint-plugin-react
• eslint-plugin-react-hooks
• eslint-plugin-next

Эти настройки имеют приоритет над конфигурацией из next.config.js.

Правила

Полный набор правил выглядит следующим образом:

Рекомендуем использовать подходящую интеграцию для отображения предупреждений и ошибок прямо в редакторе кода во время разработки.

Примеры

Линтинг пользовательских директорий и файлов

По умолчанию Next.js запускает ESLint для всех файлов в директориях pages/, app/, components/, lib/ и src/. Однако вы можете указать конкретные директории с помощью опции dirs в конфигурации eslint в next.config.js для production-сборок:

module.exports = {
  eslint: {
    dirs: ['pages', 'utils'], // Запускать ESLint только для директорий 'pages' и 'utils' во время production-сборок (next build)
  },
}

Аналогично, флаги --dir и --file можно использовать с next lint для линтинга конкретных директорий и файлов:

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

Указание корневой директории в монорепозитории

Если вы используете eslint-plugin-next в проекте, где Next.js не установлен в корневой директории (например, в монорепозитории), вы можете указать eslint-plugin-next, где находится ваше приложение Next.js, с помощью свойства settings в вашем .eslintrc:

import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname доступен начиная с Node.js v20.11.0
  baseDirectory: import.meta.dirname,
})

const eslintConfig = [
  ...compat.config({
    extends: ['next'],
    settings: {
      next: {
        rootDir: 'packages/my-app/',
      },
    },
  }),
]

export default eslintConfig

rootDir может быть путём (относительным или абсолютным), glob-шаблоном (например, "packages/*/") или массивом путей и/или шаблонов.

Отключение кеширования

Для повышения производительности информация о файлах, обработанных ESLint, по умолчанию кешируется. Кеш хранится в .next/cache или в указанной вами директории сборки. Если вы используете правила ESLint, которые зависят от содержимого нескольких исходных файлов, и вам нужно отключить кеширование, используйте флаг --no-cache с next lint.

next lint --no-cache

Отключение правил

Если вы хотите изменить или отключить какие-либо правила из поддерживаемых плагинов (react, react-hooks, next), вы можете сделать это напрямую с помощью свойства rules в вашем .eslintrc:

import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname доступен начиная с Node.js v20.11.0
  baseDirectory: import.meta.dirname,
})

const eslintConfig = [
  ...compat.config({
    extends: ['next'],
    rules: {
      'react/no-unescaped-entities': 'off',
      '@next/next/no-page-custom-font': 'off',
    },
  }),
]

export default eslintConfig

С Core Web Vitals

Набор правил next/core-web-vitals активируется при первом запуске next lint, если выбран строгий вариант.

import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname доступен начиная с Node.js v20.11.0
  baseDirectory: import.meta.dirname,
})

const eslintConfig = [
  ...compat.config({
    extends: ['next/core-web-vitals'],
  }),
]

export default eslintConfig

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 в вашу конфигурацию:

import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname доступен начиная с Node.js v20.11.0
  baseDirectory: import.meta.dirname,
})

const eslintConfig = [
  ...compat.config({
    extends: ['next/core-web-vitals', 'next/typescript'],
  }),
]

export default eslintConfig

Эти правила основаны на plugin:@typescript-eslint/recommended. Подробнее см. в typescript-eslint > Configs.

С Prettier

ESLint также включает правила форматирования кода, которые могут конфликтовать с вашей текущей настройкой Prettier. Рекомендуем включить eslint-config-prettier в вашу конфигурацию ESLint для совместной работы ESLint и Prettier.

Сначала установите зависимость:

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:

import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname доступен начиная с Node.js v20.11.0
  baseDirectory: import.meta.dirname,
})

const eslintConfig = [
  ...compat.config({
    extends: ['next', 'prettier'],
  }),
]

export default eslintConfig

Запуск линтинга для staged-файлов

Если вы хотите использовать next lint с lint-staged для запуска линтера на 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],
}

Отключение линтинга во время production-сборок

Если вы не хотите, чтобы ESLint запускался во время next build, вы можете установить опцию eslint.ignoreDuringBuilds в next.config.js в значение true:

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  eslint: {
    // Предупреждение: Это позволяет успешно завершать production-сборки,
    // даже если в вашем проекте есть ошибки ESLint.
    ignoreDuringBuilds: true,
  },
}

export default nextConfig

const nextConfig = {
  eslint: {
    // Предупреждение: Это позволяет успешно завершать production-сборки,
    // даже если в вашем проекте есть ошибки ESLint.
    ignoreDuringBuilds: true,
  },
}

export default nextConfig

Миграция существующей конфигурации

Если у вас уже настроен ESLint в вашем приложении, мы рекомендуем расширять этот плагин напрямую вместо включения eslint-config-next, за исключением нескольких случаев.

Рекомендуемый набор правил плагина

Если выполняются следующие условия:

• У вас уже установлен один или несколько следующих плагинов (отдельно или через другую конфигурацию, такую как airbnb или react-app):
  • react
  • react-hooks
  • jsx-a11y
  • import
• Вы определили специфичные parserOptions, которые отличаются от настройки Babel в Next.js (это не рекомендуется, если вы не настроили Babel вручную)
• У вас установлен eslint-plugin-import с Node.js и/или TypeScript резолверами для обработки импортов

Тогда мы рекомендуем либо удалить эти настройки, если вы предпочитаете конфигурацию этих свойств в 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

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

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

Это устраняет риск конфликтов или ошибок, которые могут возникнуть из-за импорта одного и того же плагина или парсера в нескольких конфигурациях.

Дополнительные конфигурации

Если вы уже используете отдельную конфигурацию ESLint и хотите включить eslint-config-next, убедитесь, что она расширяется последней после других конфигураций. Например:

import js from '@eslint/js'
import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname доступен начиная с Node.js v20.11.0
  baseDirectory: import.meta.dirname,
  recommendedConfig: js.configs.recommended,
})

const eslintConfig = [
  ...compat.config({
    extends: ['eslint:recommended', 'next'],
  }),
]

export default eslintConfig

Конфигурация next уже обрабатывает установку значений по умолчанию для свойств parser, plugins и settings. Нет необходимости вручную переопределять эти свойства, если только вам не требуется другая конфигурация для вашего случая использования.

Если вы включаете какие-либо другие общие конфигурации, вам нужно убедиться, что эти свойства не перезаписываются и не изменяются. В противном случае мы рекомендуем удалить любые конфигурации, которые дублируют поведение конфигурации next, или расширяться напрямую из плагина ESLint для Next.js, как упоминалось выше.