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. После настройки ESLint будет автоматически запускаться при каждой сборке (next build). Ошибки прервут сборку, а предупреждения — нет.

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

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

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

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

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

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

• 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.

TypeScript

В дополнение к правилам ESLint от Next.js, create-next-app --typescript также добавит специфичные для TypeScript правила линтинга через next/typescript в вашу конфигурацию:

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

Эти правила основаны на 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:

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

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

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

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