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) включает все необходимое для оптимального опыта проверки кода «из коробки» в 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 не установлен в корневом каталоге (например, в monorepo), вы можете указать eslint-plugin-next местоположение вашего приложения 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 для билдов в продакшене:

module.exports = {
  eslint: {
    dirs: ['pages', 'utils'], // Only run ESLint on the 'pages' and 'utils' directories during production builds (next build)
  },
}

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

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

Кэширование

Для повышения производительности информация о файлах, обработанных ESLint, кэшируется по умолчанию. Она хранится в .next/cache или в вашем определённом каталоге билда dist. Если вы используете правила 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"
  }
}

Основные показатели качества веб-сайта

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

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

next/core-web-vitals обновляет eslint-plugin-next для отображения ошибок по ряду правил, которые по умолчанию являются предупреждениями, если они влияют на Основные показатели качества веб-сайта.

Точка входа 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 для запуска линтера на подготовленных файлах 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, как указано выше.