ESLint

Next.js предоставляет встроенную поддержку ESLint из коробки. Добавьте next lint как скрипт в package.json:

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

Затем запустите npm run lint или yarn lint:

yarn lint

Если ESLint ещё не настроен в вашем приложении, вам будет предложено пройти процесс установки и настройки.

yarn lint

Вы увидите запрос следующего вида:

? Как вы хотите настроить ESLint?

❯ Строгий (рекомендуется)
Базовый
Отмена

Можно выбрать один из трёх вариантов:

• Строгий: Включает базовую конфигурацию ESLint от Next.js вместе с более строгим набором правил Core Web Vitals. Это рекомендуемая конфигурация для разработчиков, впервые настраивающих ESLint.

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

• Базовый: Включает только базовую конфигурацию ESLint от Next.js.

  {
    "extends": "next"
  }

• Отмена: Не включает никакой конфигурации ESLint. Выбирайте этот вариант только если планируете настроить собственную конфигурацию ESLint.

Если выбран один из двух вариантов конфигурации, Next.js автоматически установит eslint и eslint-config-next как зависимости вашего приложения и создаст файл .eslintrc.json в корне проекта с выбранной конфигурацией.

Теперь вы можете запускать next lint для проверки ошибок. После настройки ESLint будет автоматически запускаться при каждой сборке (next build). Ошибки остановят сборку, а предупреждения — нет.

Если вы не хотите, чтобы ESLint запускался во время next build, обратитесь к документации Игнорирование ESLint.

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

Конфигурация ESLint

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

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

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

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

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

Плагин ESLint

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

Включено в рекомендуемой конфигурации

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

Пользовательские настройки

rootDir

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

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

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

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

По умолчанию 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 файлах кэшируется по умолчанию. Кэш хранится в .next/cache или в указанной директории сборки. Если вы используете правила ESLint, зависящие от содержимого нескольких файлов, и нужно отключить кэш, используйте флаг --no-cache с next lint.

next lint --no-cache

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

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

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

Core Web Vitals

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

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

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

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:

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

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

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

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

Если ESLint уже настроен в вашем приложении и выполняется одно из следующих условий:

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

Тогда рекомендуем либо удалить эти настройки, если вы предпочитаете конфигурацию из eslint-config-next, либо расширить конфигурацию непосредственно из плагина Next.js ESLint:

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, убедитесь, что она расширяется последней после других конфигураций. Например:

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

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

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