Структура файла конфигурации

Конфигурация ESLint определяет поведение анализатора кода: какие правила активны, как обрабатываются различные файлы проекта, какие плагины подключены и каким образом интерпретируется синтаксис JavaScript. Структура конфигурации эволюционировала от каскадных .eslintrc файлов к современной плоской модели eslint.config.js, что повлияло на способ композиции и расширения правил.

Основные формы конфигурации

Классическая (legacy) система .eslintrc

Исторически ESLint использовал несколько вариантов файлов конфигурации:

  • .eslintrc
  • .eslintrc.json
  • .eslintrc.yml
  • .eslintrc.js
  • поле eslintConfig в package.json

На уровне структуры все они описывали один и тот же набор сущностей:

{
  "env": {},
  "extends": [],
  "parser": "",
  "parserOptions": {},
  "plugins": [],
  "rules": {},
  "settings": {},
  "overrides": []
}

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

Flat Config (eslint.config.js)

Современный формат ESLint основан на плоской структуре конфигурации. Вместо каскадного наследования используется массив объектов:

export default [
  {
    files: ["**/*.js"],
    languageOptions: {},
    rules: {},
    plugins: {}
  }
];

Главное отличие — отсутствие скрытого наследования. Все слои конфигурации объявлены явно.

Ключевые секции конфигурации

rules

Секция rules определяет набор правил линтинга. Каждое правило задаётся парой: имя → уровень/настройка.

{
  "rules": {
    "no-unused-vars": "error",
    "no-console": "warn",
    "eqeqeq": "error"
  }
}

Уровни:

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

В расширенной форме допускается конфигурация с параметрами:

{
  "rules": {
    "quotes": ["error", "single"],
    "semi": ["error", "always"]
  }
}

parser

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

{
  "parser": "@babel/eslint-parser"
}

Использование кастомных парсеров требуется при работе с:

  • TypeScript
  • экспериментальными предложениями ECMAScript
  • нестандартными синтаксическими расширениями

parserOptions

Секция управляет параметрами синтаксического анализа.

{
  "parserOptions": {
    "ecmaVersion": 2023,
    "sourceType": "module",
    "ecmaFeatures": {
      "jsx": true
    }
  }
}

Основные поля:

  • ecmaVersion — версия ECMAScript
  • sourceType — "script" или "module"
  • ecmaFeatures — дополнительные флаги (например JSX)

env

env определяет предустановленные глобальные переменные окружения.

{
  "env": {
    "browser": true,
    "node": true,
    "es2021": true
  }
}

Каждое значение автоматически добавляет соответствующие глобальные объекты и настройки синтаксиса.

globals

Позволяет вручную объявлять глобальные переменные.

{
  "globals": {
    "MyGlobal": "readonly",
    "DEBUG": "writable"
  }
}

Варианты режимов:

  • "readonly"
  • "writable"
  • "off"

plugins

Подключение расширений ESLint.

{
  "plugins": ["react", "import"]
}

Плагины добавляют:

  • новые правила
  • процессоры файлов
  • конфигурационные пресеты

В flat-конфигурации плагины задаются как объект:

import react from "eslint-plugin-react";

export default [
  {
    plugins: {
      react
    }
  }
];

extends

Механизм наследования конфигураций.

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

Источники extends:

  • встроенные пресеты ESLint
  • конфигурации плагинов
  • внешние пакеты
  • локальные файлы

Каскадность и приоритеты

Legacy cascade

В .eslintrc конфигурации объединяются по принципу:

  1. Глобальная конфигурация
  2. Конфигурации родительских директорий
  3. Локальная конфигурация
  4. overrides

Каждый уровень может переопределять предыдущий.

Flat config precedence

В eslint.config.js порядок массива определяет приоритет:

export default [
  { rules: { "no-console": "off" } },
  { rules: { "no-console": "error" } }
];

Последний применённый объект имеет более высокий приоритет.

overrides

В legacy системе overrides позволяет применять разные настройки для различных файлов.

{
  "overrides": [
    {
      "files": ["*.test.js"],
      "rules": {
        "no-unused-expressions": "off"
      }
    }
  ]
}

Поля внутри overrides повторяют основную структуру конфигурации.

settings

Общая область хранения данных, используемых плагинами.

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

ESLint не интерпретирует эти данные напрямую, передавая их плагинам.

ignorePatterns

Управление исключением файлов из анализа.

{
  "ignorePatterns": ["dist/", "node_modules/"]
}

В flat-конфигурации используется поле ignores:

export default [
  {
    ignores: ["dist/**"]
  }
];

Структура flat-конфигурации

Flat config представляет собой последовательность объектов, каждый из которых описывает отдельный слой правил.

export default [
  // базовый слой
  {
    files: ["**/*.{js,mjs}"],
    languageOptions: {
      ecmaVersion: 2022,
      sourceType: "module"
    },
    rules: {
      "no-var": "error"
    }
  },

  // слой для тестов
  {
    files: ["**/*.test.js"],
    rules: {
      "no-unused-expressions": "off"
    }
  }
];

files и область применения

Поле files определяет, к каким файлам применяется конфигурационный блок.

{
  files: ["src/**/*.js"]
}

Поддерживаются glob-шаблоны:

  • * — один уровень
  • ** — рекурсивно
  • ? — один символ

languageOptions

В flat-конфигурации parser и parserOptions объединены в languageOptions:

{
  languageOptions: {
    ecmaVersion: 2023,
    sourceType: "module",
    parser: someParser
  }
}

Также сюда входят:

  • globals
  • ecmaVersion
  • sourceType

processor

Процессоры преобразуют файлы перед анализом ESLint.

{
  "processor": "markdown/markdown"
}

Используется для:

  • Markdown файлов
  • Vue SFC
  • кастомных форматов

Модульная структура конфигурации

В современных проектах конфигурация часто разделяется на модули:

eslint.config.js
eslint.base.js
eslint.react.js
eslint.node.js

И объединяется:

import base from "./eslint.base.js";
import react from "./eslint.react.js";

export default [
  ...base,
  ...react
];

Конфигурационные источники и порядок разрешения

В legacy системе ESLint ищет конфигурацию в следующем порядке:

  1. eslintConfig в package.json
  2. .eslintrc.js
  3. .eslintrc.cjs
  4. .eslintrc.json
  5. .eslintrc.yml
  6. .eslintrc

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

Переход от legacy к flat-конфигурации

Flat config устраняет следующие ограничения legacy модели:

  • скрытое наследование
  • неоднозначность приоритетов
  • сложность отладки каскада
  • множественные источники конфигурации

Структура становится линейной, состоящей из массива независимых блоков, где каждый блок определяет:

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

Композиция конфигураций

Конфигурации могут комбинироваться на уровне Jav * aScript:

const baseRules = {
  "no-console": "warn"
};

const strictRules = {
  "no-console": "error",
  "eqeqeq": "error"
};

export default [
  {
    rules: baseRules
  },
  {
    rules: strictRules
  }
];

Такой подход делает конфигурацию программируемой, а не декларативной в чистом виде.

Локальная и глобальная конфигурация

Локальная конфигурация относится к конкретному проекту или директории. Глобальная задаётся через:

  • ~/.eslintrc
  • глобальные настройки CLI

В flat-системе глобальная конфигурация обычно заменяется отдельным базовым модулем, импортируемым во все проекты.

Связь конфигурации с системой правил

Каждый конфигурационный файл напрямую влияет на:

  • загрузку набора правил
  • способ парсинга AST
  • анализ глобальных переменных
  • фильтрацию файлов
  • подключение плагинов

Структура конфигурации определяет весь pipeline работы ESLint от чтения файла до выдачи диагностических сообщений.

Оглавление