Установка и подключение плагина

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

Типичная структура плагина включает:

  • набор правил (rules)
  • пресеты конфигураций (configs)
  • вспомогательные функции
  • иногда кастомные парсеры или процессоры файлов

Большинство плагинов публикуются в виде пакетов с префиксом eslint-plugin-, однако при подключении используется сокращённое имя без префикса.

Установка плагина через менеджеры пакетов

Плагин устанавливается как обычная зависимость проекта. ESLint не включает сторонние плагины по умолчанию, поэтому они всегда добавляются отдельно.

npm

npm install eslint-plugin-react --save-dev

yarn

yarn add eslint-plugin-react -D

pnpm

pnpm add eslint-plugin-react -D

При установке важно учитывать версию ESLint. Многие плагины имеют ограничения совместимости, указанные в peerDependencies. При несовпадении версий возможны ошибки загрузки конфигурации или частичная недоступность правил.

Подключение плагина в классической конфигурации (.eslintrc)

В традиционной системе конфигурации ESLint (JSON, YAML или JS-файл .eslintrc) плагин подключается через поле plugins.

Базовое подключение

{
  "plugins": ["react"]
}

Сокращённое имя react соответствует пакету eslint-plugin-react.

Подключение само по себе не активирует правила. Оно лишь делает их доступными для использования.

Использование правил плагина

После подключения плагина правила становятся доступными через пространство имён:

{
  "rules": {
    "react/jsx-uses-react": "error",
    "react/jsx-uses-vars": "error"
  }
}

Каждое правило имеет формат:

<plugin>/<ruleName>

Режимы работы правил:

  • "off" — отключено
  • "warn" — предупреждение
  • "error" — ошибка

Подключение готовых конфигураций плагина

Многие плагины предоставляют предустановленные конфигурации через поле extends.

Пример для React

{
  "extends": ["plugin:react/recommended"]
}

Формат записи:

plugin:<pluginName>/<configName>

Такие конфигурации могут включать:

  • набор правил
  • рекомендуемые значения
  • дополнительные настройки среды

Передача настроек плагину

Некоторые плагины требуют явной конфигурации через settings.

{
  "settings": {
    "react": {
      "version": "detect"
    }
  }
}

Подобный механизм используется для автоматического определения версии библиотек или поведения анализа AST.

Переход на flat config (eslint.config.js)

Современная система ESLint использует плоскую конфигурацию, где плагины импортируются как модули.

Установка плагина

npm install eslint-plugin-react -D

Подключение в eslint.config.js

import react from "eslint-plugin-react";

export default [
  {
    plugins: {
      react
    },
    rules: {
      "react/jsx-uses-react": "error"
    }
  }
];

В отличие от .eslintrc, здесь отсутствует строковое объявление плагина — используется объектное подключение.

Использование конфигураций в flat config

Некоторые плагины экспортируют готовые наборы конфигураций:

import react from "eslint-plugin-react";

export default [
  react.configs.recommended
];

Конфигурации могут быть массивами или объектами, которые объединяются с основной конфигурацией проекта.

Совместимость версий ESLint и плагинов

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

  • невозможность загрузки конфигурации
  • ошибки парсинга файлов
  • отсутствие правил в списке доступных
  • некорректная работа линтера в IDE

Часто используется стратегия фиксирования версий:

eslint: ^8.x
eslint-plugin-react: ^7.x

Подключение нескольких плагинов

Проекты обычно используют комбинацию нескольких расширений:

{
  "plugins": ["react", "import", "jsx-a11y"]
}

И соответствующие правила:

{
  "rules": {
    "import/no-unresolved": "error",
    "jsx-a11y/alt-text": "error",
    "react/no-unknown-property": "error"
  }
}

Плагины и парсеры

Некоторые плагины требуют замены парсера для поддержки нестандартного синтаксиса.

Пример с TypeScript

npm install @typescript-eslint/parser @typescript-eslint/eslint-plugin -D
{
  "parser": "@typescript-eslint/parser",
  "plugins": ["@typescript-eslint"],
  "extends": ["plugin:@typescript-eslint/recommended"]
}

Парсер отвечает за преобразование кода в AST, а плагин — за правила анализа.

Работа с peerDependencies

Многие плагины объявляют ESLint как peer dependency:

{
  "peerDependencies": {
    "eslint": ">=8.0.0"
  }
}

Это означает отсутствие встроенной версии ESLint внутри плагина. Несоблюдение требований приводит к конфликтам зависимостей в node_modules.

Монорепозитории и локальные плагины

В монорепозиториях плагины могут подключаться локально через workspace-зависимости:

pnpm add eslint-plugin-custom -w

Или через относительный пакет внутри репозитория. Такие плагины используются для унификации внутренних правил кодовой базы.

Динамическое подключение плагинов

В flat config возможно программное формирование конфигурации:

import react from "eslint-plugin-react";
import importPlugin from "eslint-plugin-import";

const plugins = {
  react,
  import: importPlugin
};

export default [
  {
    plugins,
    rules: {
      "react/jsx-uses-react": "error",
      "import/no-cycle": "warn"
    }
  }
];

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

Частые ошибки подключения

  • использование полного имени пакета вместо сокращённого (eslint-plugin-react вместо react)
  • подключение правил без регистрации плагина в plugins
  • несовпадение версии ESLint и плагина
  • попытка использовать extends без установленного плагина
  • смешивание flat config и .eslintrc в одном проекте без переходного слоя

Структура поиска правил внутри плагина

ESLint резолвит правила по следующему пути:

plugin name → exports → rules → rule name

Пример:

react/no-unknown-property

означает:

  • плагин react
  • правило no-unknown-property внутри него

Подключение плагинов в CI/CD

В автоматизированных пайплайнах ESLint запускается как отдельный этап:

npx eslint "src/**/*.{js,ts,jsx,tsx}"

Плагины должны быть установлены на этапе npm ci или аналогичном, иначе линтер завершится с ошибкой отсутствующих модулей.

Использование нескольких конфигураций плагина одновременно

Некоторые плагины предоставляют разные уровни строгости:

  • recommended
  • strict
  • all

Пример:

{
  "extends": [
    "plugin:react/recommended",
    "plugin:react/jsx-runtime"
  ]
}

Конфигурации объединяются сверху вниз, где последующие значения переопределяют предыдущие.

Оглавление