Файлы конфигурации

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

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

Файл конфигурации ESLint может быть назван одним из следующих способов:

eslint.config.js
eslint.config.mjs
eslint.config.cjs
eslint.config.ts (требует дополнительной настройки)
eslint.config.mts (требует дополнительной настройки)
eslint.config.cts (требует дополнительной настройки)

Он должен быть помещен в корневую директорию вашего проекта и экспортировать массив объектов конфигурации. Вот пример:

// eslint.config.js
export default [
    {
        rules: {
            semi: "error",
            "prefer-const": "error"
        }
    }
];

В этом примере массив конфигурации содержит только один объект конфигурации. Объект конфигурации включает два правила: semi и prefer-const. Эти правила применяются ко всем файлам, которые ESLint обрабатывает с использованием этого файла конфигурации.

Если ваш проект не указывает "type":"module" в своём файле package.json, то eslint.config.js должен быть в формате CommonJS, например:

// eslint.config.js
module.exports = [
    {
        rules: {
            semi: "error",
            "prefer-const": "error"
        }
    }
];

Объекты конфигурации

Каждый объект конфигурации содержит всю информацию, необходимую ESLint для выполнения проверки набора файлов. Каждый объект конфигурации состоит из следующих свойств:

name — имя объекта конфигурации. Оно используется в сообщениях об ошибках и инспекторе конфигурации, чтобы помочь определить, какой объект конфигурации используется. (Имена конфигураций)
files — массив шаблонов glob, указывающих файлы, к которым должен применяться объект конфигурации. Если не указано, объект конфигурации применяется ко всем файлам, соответствующим любому другому объекту конфигурации.
ignores — массив шаблонов glob, указывающих файлы, к которым объект конфигурации не должен применяться. Если не указано, объект конфигурации применяется ко всем файлам, соответствующим files. Если ignores используется без других ключей в объекте конфигурации, то шаблоны действуют как глобальные исключения.
languageOptions — объект, содержащий настройки, связанные с конфигурацией JavaScript для проверки.
- ecmaVersion — версия ECMAScript для поддержки. Может быть указан год (например, 2022) или версия (например, 5). Установлено на "latest" для самой последней поддерживаемой версии. (по умолчанию: "latest")
- sourceType — тип исходного кода JavaScript. Возможные значения: "script" для традиционных файлов скриптов, "module" для модулей ECMAScript (ESM) и "commonjs" для файлов CommonJS. (по умолчанию: "module" для .js и .mjs файлов; "commonjs" для .cjs файлов)
- globals — объект, определяющий дополнительные объекты, которые должны быть добавлены в глобальную область видимости во время проверки.
- parser — объект, содержащий метод parse() или метод parseForESLint(). (по умолчанию: espree)
- parserOptions — объект, определяющий дополнительные параметры, передаваемые непосредственно методу parse() или parseForESLint() парсера. Доступные параметры зависят от парсера.
linterOptions — объект, содержащий настройки, связанные с процессом проверки.
- noInlineConfig — логическое значение, указывающее, разрешена ли инлайновая конфигурация.
- reportUnusedDisableDirectives — строка уровня серьёзности, указывающая, как отслеживать и сообщать об отключаемых/включаемых директивах. Для обратной совместимости true эквивалентно "warn", а false эквивалентно "off". (по умолчанию: "warn").
processor — либо объект, содержащий методы preprocess() и postprocess(), либо строка, указывающая имя процессора внутри плагина (например, "pluginName/processorName").
plugins — объект, содержащий сопоставление имен плагинов с объектами плагинов. Когда files указано, эти плагины доступны только для соответствующих файлов.
rules — объект, содержащий настроенные правила. Когда files или ignores указаны, эти конфигурации правил доступны только для соответствующих файлов.
settings — объект, содержащий пары имя-значение информации, которая должна быть доступна всем правилам.

Указание `files` и `ignores`

Вы можете использовать комбинацию files и ignores для определения, к каким файлам должен применяться объект конфигурации, и к каким нет. По умолчанию ESLint проверяет файлы, соответствующие шаблонам **/*.js, **/*.cjs, и **/*.mjs. Эти файлы всегда соответствуют, если вы явно не исключите их с помощью глобальных исключений. Поскольку объекты конфигурации, не определяющие files или ignores, применяются ко всем файлам, соответствующим любому другому объекту конфигурации, они будут применяться ко всем файлам JavaScript. Например:

// eslint.config.js
export default [
    {
        rules: {
            semi: "error"
        }
    }
];

С этой конфигурацией правило semi включено для всех файлов, которые соответствуют стандартным файлам ESLint. Таким образом, если вы передадите example.js в ESLint, правило semi будет применено. Если вы передадите файл, не являющийся JavaScript, например example.txt, правило semi не будет применено, так как нет других объектов конфигурации, соответствующих этому имени файла. (ESLint выведет сообщение об ошибке, информируя вас о том, что файл был пропущен из-за отсутствия конфигурации.)

Исключение файлов с `ignores`

Вы можете ограничить, к каким файлам применяется объект конфигурации, указав комбинацию шаблонов files и ignores. Например, вы можете захотеть, чтобы определенные правила применялись только к файлам в вашей директории src:

// eslint.config.js
export default [
    {
        files: ["src/**/*.js"],
        rules: {
            semi: "error"
        }
    }
];

Здесь только файлы JavaScript в директории src имеют применённое правило semi. Если вы запустите ESLint на файлах в другой директории, этот объект конфигурации будет пропущен. Добавив ignores, вы также можете исключить некоторые файлы из src из этого объекта конфигурации:

export default [
    {
        files: ["src/**/*.js"],
        ignores: ["**/*.config.js"],
        rules: {
            semi: "error"
        }
    }
];

Этот объект конфигурации соответствует всем файлам JavaScript в директории src за исключением тех, что оканчиваются на .config.js. Вы также можете использовать отрицательные шаблоны в ignores для исключения файлов из шаблонов исключений, например:

export default [
    {
        files: ["src/**/*.js"],
        ignores: ["**/*.config.js", "!**/eslint.config.js"],
        rules: {
            semi: "error"
        }
    }
];

Здесь объект конфигурации исключает файлы, оканчивающиеся на .config.js, за исключением eslint.config.js. Для этого файла всё ещё применено semi.

Неглобальные шаблоны ignores могут соответствовать только именам файлов. Шаблон, подобный "dir-to-exclude/", ничего не исключит. Чтобы исключить всё содержимое конкретной директории, следует использовать шаблон, подобный "dir-to-exclude/**".

Если ignores используется без files и есть другие ключи (например, rules), то объект конфигурации применяется ко всем проверяемым файлам за исключением тех, которые исключены ignores, например:

export default [
    {
        ignores: ["**/*.config.js"],
        rules: {
            semi: "error"
        }
    }
];

Этот объект конфигурации применяется ко всем файлам JavaScript, за исключением файлов, оканчивающихся на .config.js. Эффективно, это то же самое, что если бы files был бы установлен в **/*. В общем случае, рекомендуется всегда включать files если вы указываете ignores.

Обратите внимание, что когда files не указан, отрицательные шаблоны ignores не приводят к автоматической проверке соответствующих файлов. ESLint проверяет только файлы, которые соответствуют либо по умолчанию, либо шаблону files, который не является * и не оканчивается на /* или /**.

Указание файлов с произвольными расширениями

Для проверки файлов с расширениями, отличными от стандартных .js, .cjs и .mjs, включите их в files с шаблоном в формате "**/*.extension". Любой шаблон подойдёт, кроме тех, которые * или оканчиваются на /* или /**. Например, чтобы проверить файлы TypeScript с расширениями .ts, .cts и .mts, вы бы указали объект конфигурации так:

// eslint.config.js
export default [
    {
        files: [
            "**/*.ts",
            "**/*.cts",
            "**.*.mts"
        ]
    },
    // ...other config
];

Указание файлов без расширения

Файлы без расширения могут быть найдены с помощью шаблона !(*.*). Например:

// eslint.config.js
export default [
    {
        files: ["**/!(*.*)"]
    },
    // ...other config
];

Вышеуказанная конфигурация проверяет файлы без расширения, кроме стандартных расширений .js, .cjs и .mjs во всех директориях.

Глобальное игнорирование файлов с `ignores`

Если ignores используется без каких-либо других ключей в объекте конфигурации, то шаблоны действуют как глобальные игнорирования. Вот пример:

// eslint.config.js
export default [
    {
        ignores: [".config/*"]
    }
];

Эта конфигурация указывает, что все файлы в каталоге .config должны быть проигнорированы. Этот шаблон добавляется после стандартных шаблонов, которые составляют ["**/node_modules/", ".git/"].

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

Каскадные объекты конфигурации

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

// eslint.config.js
export default [
    {
        files: ["**/*.js"],
        languageOptions: {
            globals: {
                MY_CUSTOM_GLOBAL: "readonly"
            }
        }
    },
    {
        files: ["tests/**/*.js"],
        languageOptions: {
            globals: {
                it: "readonly",
                describe: "readonly"
            }
        }
    }
];

Используя эту конфигурацию, все файлы JavaScript определяют пользовательский глобальный объект, называемый MY_CUSTOM_GLOBAL, а файлы JavaScript в каталоге tests дополнительно определяют it и describe в качестве глобальных объектов, помимо MY_CUSTOM_GLOBAL. Для любого файла JavaScript в каталоге тестов применяются оба объекта конфигурации, поэтому languageOptions.globals объединяются для создания конечного результата.

Настройка опций линтера

Опции, специфичные для процесса линтинга, можно настроить, используя объект linterOptions. Они влияют на то, как происходит линтинг, и не влияют на интерпретацию исходного кода файла.

Отключение встроенной конфигурации

Встроенная конфигурация реализована с помощью комментария /*eslint*/, например /*eslint semi: error*/. Вы можете запретить встроенную конфигурацию, установив noInlineConfig в true. При включении вся встроенная конфигурация игнорируется. Вот пример:

// eslint.config.js
export default [
    {
        files: ["**/*.js"],
        linterOptions: {
            noInlineConfig: true
        }
    }
];

Отчет об использовании отключенных директив

Директивы отключения и включения, такие как /*eslint-disable*/, /*eslint-enable*/ и /*eslint-disable-next-line*/, используются для отключения правил ESLint в определенных частях кода. По мере изменения кода возможно, что эти директивы больше не нужны, поскольку код изменился таким образом, что правило больше не срабатывает. Вы можете включить отчет об этих неиспользуемых отключенных директивах, установив опцию reportUnusedDisableDirectives на строку серьезности, как в этом примере:

// eslint.config.js
export default [
    {
        files: ["**/*.js"],
        linterOptions: {
            reportUnusedDisableDirectives: "error"
        }
    }
];

Это значение по умолчанию "warn".

Вы можете переопределить это значение, используя --report-unused-disable-directives или --report-unused-disable-directives-severity параметры командной строки.

Для совместимости со старыми версиями true эквивалентно "warn", а false эквивалентно "off".

Настройка правил

Вы можете настроить любое количество правил в объекте конфигурации, добавив свойство rules, содержащее объект с вашими конфигурациями правил. Имена в этом объекте — имена правил, а значения — конфигурации для каждого из этих правил. Вот пример:

// eslint.config.js
export default [
    {
        rules: {
            semi: "error"
        }
    }
];

Этот объект конфигурации указывает, что правило semi должно быть включено с серьезностью "error". Вы также можете предоставить параметры правилу, указав массив, где первый элемент — серьезность, а каждый последующий элемент — параметр для правила. Например, вы можете изменить правило semi для запрета использования точек с запятой, передав "never" в качестве параметра:

// eslint.config.js
export default [
    {
        rules: {
            semi: ["error", "never"]
        }
    }
];

Каждое правило определяет свои собственные параметры и может быть любым допустимым типом данных JSON. Для получения дополнительной информации о доступных параметрах, пожалуйста, обратитесь к документации по интересующему вас правилу.

Дополнительную информацию о настройке правил см. в разделе Настройка правил.

Настройка общих настроек

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

// eslint.config.js
export default [
    {
        settings: {
            sharedData: "Hello"
        },
        plugins: {
            customPlugin: {
                rules: {
                    "my-rule": {
                        meta: {
                            // custom rule's meta information
                        },
                        create(context) {
                            const sharedData = context.settings.sharedData;
                            return {
                                // code
                            };
                        }
                    }
                }
            }
        },
        rules: {
            "customPlugin/my-rule": "error"
        }
    }
];

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

ESLint имеет две предопределенные конфигурации для JavaScript:

js.configs.recommended — включает правила, которые ESLint рекомендует использовать всем для предотвращения потенциальных ошибок
js.configs.all — включает все правила, поставляемые с ESLint

Чтобы включить эти предопределенные конфигурации, установите пакет @eslint/js, а затем внесите любые изменения в другие свойства в последующих объектах конфигурации:

// eslint.config.js
import js from "@eslint/js";

export default [
    js.configs.recommended,
    {
        rules: {
            "no-unused-vars": "warn"
        }
    }
];

Здесь предопределенная конфигурация js.configs.recommended применяется в первую очередь, а затем другой объект конфигурации добавляет необходимую конфигурацию для no-unused-vars.

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

Конвенции именования конфигураций

Свойство name необязательно, но рекомендуется предоставлять имя для каждого объекта конфигурации, особенно при создании общих конфигураций. Имя используется в сообщениях об ошибках и инспекторе конфигураций для облегчения идентификации используемого объекта конфигурации.

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

Например, если вы создаёте объект конфигурации для плагина под названием eslint-plugin-example, вы можете добавить name к объектам конфигурации с префиксом example/:

export default {
    configs: {
        recommended: {
            name: "example/recommended",
            rules: {
                "no-unused-vars": "warn"
            }
        },
        strict: {
            name: "example/strict",
            rules: {
                "no-unused-vars": "error"
            }
        }
    }
};

При экспонировании массивов объектов конфигурации name может иметь дополнительные уровни охватывания для облегчения идентификации объекта конфигурации. Например:

export default {
    configs: {
        strict: [
            {
                name: "example/strict/language-setup",
                languageOptions: {
                    ecmaVersion: 2024
                }
            },
            {
                name: "example/strict/sub-config",
                file: ["src/**/*.js"],
                rules: {
                    "no-unused-vars": "error"
                }
            }
        ]
    }
}

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

Общий пакет конфигурации — это пакет npm, который экспортирует объект конфигурации или массив. Этот пакет необходимо установить в качестве зависимости в ваш проект, а затем использовать в вашем файле eslint.config.js. Например, чтобы использовать общий пакет конфигурации под названием eslint-config-example, ваш файл конфигурации будет выглядеть так:

// eslint.config.js
import exampleConfig from "eslint-config-example";

export default [
    exampleConfig,

    // your modifications
    {
        rules: {
            "no-unused-vars": "warn"
        }
    }
];

В этом примере exampleConfig — это объект, поэтому вы вставляете его непосредственно в массив конфигураций.

Некоторые общие пакеты конфигураций экспортируют массив вместо этого, в этом случае вам потребуется использовать оператор spread для вставки этих элементов в массив конфигураций. Например:

// eslint.config.js
import exampleConfigs from "eslint-config-example";

export default [
    ...exampleConfigs,

    // your modifications
    {
        rules: {
            "no-unused-vars": "warn"
        }
    }
];

Обратитесь к документации используемого вами пакета общей конфигурации, чтобы определить, экспортирует ли он объект или массив.

Для получения дополнительной информации о том, как объединять общие конфигурации с вашими предпочтениями, см. Объединение конфигураций.

Разрешение файла конфигурации

При запуске ESLint в командной строке он сначала проверяет текущую рабочую директорию на наличие eslint.config.js. Если этот файл найден, поиск останавливается, в противном случае он проверяет наличие eslint.config.mjs. Если этот файл найден, поиск останавливается, в противном случае он проверяет наличие eslint.config.cjs. Если ни один из файлов не найден, он проверяет родительскую директорию для каждого файла. Этот поиск продолжается до тех пор, пока не будет найден файл конфигурации или не будет достигнута корневая директория.

Вы можете предотвратить этот поиск eslint.config.js с помощью параметра -c или --config в командной строке для указания альтернативного файла конфигурации, например:

npx eslint --config some-other-file.js **/*.js

В этом случае ESLint не ищет eslint.config.js и вместо этого использует some-other-file.js.

Экспериментальное разрешение файла конфигурации

Вы можете использовать флаг unstable_config_lookup_from_file для изменения способа поиска ESLint файлов конфигурации. Вместо поиска с текущей рабочей директории, ESLint будет искать файл конфигурации, начиная с директории файла, который проходит линтер, и затем искать вверх по родительским каталогам, пока не найдёт файл eslint.config.js (или любое другое расширение файла конфигурации). Это поведение лучше подходит для монорепозиториев, где каждый подкаталог может иметь свой собственный файл конфигурации.

Чтобы использовать эту функцию в командной строке, используйте флаг --flag:

npx eslint --flag unstable_config_lookup_from_file .

Дополнительную информацию об использовании флагов функций см. в разделе Флаги функций.

Файлы конфигурации TypeScript

Для активации этой функции необходимо включить флаг функции unstable_ts_config:

npx eslint --flag unstable_ts_config

Дополнительную информацию об использовании флагов функций см. в разделе Флаги функций.

Для Deno и Bun, файлы конфигурации TypeScript поддерживаются в стандартном режиме; для Node.js необходимо установить необязательную зависимость разработки jiti версии 2.0.0 или выше в вашем проекте (эта зависимость не устанавливается ESLint автоматически):

npm install -D jiti
# or
yarn add --dev jiti
# or
pnpm add -D jiti

Затем вы можете создать файл конфигурации с расширением .ts, .mts, или .cts, и экспортировать массив объектов конфигурации. Вот пример в формате ESM:

import js from "@eslint/js";
import type { Linter } from "eslint";

export default [
  js.configs.recommended,
  {
    rules: {
      "no-console": [0],
    },
  },
] satisfies Linter.Config[];

Вот пример в формате CommonJS:

import type { Linter } from "eslint";
const eslint = require("@eslint/js");

const config: Linter.Config[] = [
  eslint.configs.recommended,
  {
    rules: {
      "no-console": [0],
    },
  },
];

module.exports = config;

Порядок применения файлов конфигурации

Если у вас есть несколько файлов конфигурации ESLint, ESLint отдаёт предпочтение файлам JavaScript перед файлами TypeScript. Порядок приоритета следующий:

eslint.config.js
eslint.config.mjs
eslint.config.cjs
eslint.config.ts
eslint.config.mts
eslint.config.cts

Чтобы переопределить это поведение, используйте параметр командной строки --config или -c для указания другого файла конфигурации:

npx eslint --flag unstable_ts_config --config eslint.config.ts

© OpenJS Foundation and other contributors
Licensed under the MIT License.
https://eslint.org/docs/latest/use/configure/configuration-files

Файлы конфигурации

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

Объекты конфигурации

Указание files и ignores

Исключение файлов с ignores

Указание файлов с произвольными расширениями

Указание файлов без расширения

Глобальное игнорирование файлов с ignores

Каскадные объекты конфигурации

Настройка опций линтера

Отключение встроенной конфигурации

Отчет об использовании отключенных директив

Настройка правил

Настройка общих настроек

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

Конвенции именования конфигураций

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

Разрешение файла конфигурации

Экспериментальное разрешение файла конфигурации

Файлы конфигурации TypeScript

Порядок применения файлов конфигурации

Указание `files` и `ignores`

Исключение файлов с `ignores`

Глобальное игнорирование файлов с `ignores`