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 не установлен в корневом каталоге (например, в монорепозитории), вы можете указать 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 или в вашем определённом каталоге сборки . Если вы используете правила 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 выполняется в первый раз и выбрано значение strict.

{
  "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, как указано выше.