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

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

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

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

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

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

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
	{
		rules: {
			semi: "error",
			"prefer-const": "error",
		},
	},
]);

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

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

// eslint.config.js
const { defineConfig } = require("eslint/config");

module.exports = defineConfig([
	{
		rules: {
			semi: "error",
			"prefer-const": "error",
		},
	},
]);

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

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

• name — имя объекта конфигурации. Оно используется в сообщениях об ошибках и в инспекторе конфигурации, чтобы определить, какой объект конфигурации используется. (Соглашения об именовании)
• basePath — строка, задающая путь к подкаталогу, к которому должен применяться объект конфигурации. Путь может быть относительным или абсолютным.
• files — массив шаблонов glob, указывающих файлы, к которым должен применяться объект конфигурации. Если свойство не задано, объект конфигурации применяется ко всем файлам, соответствующим любому другому объекту конфигурации.
• ignores — массив шаблонов glob, указывающих файлы, к которым не должен применяться объект конфигурации. Если свойство не задано, объект конфигурации применяется ко всем файлам, соответствующим files. Если ignores используется без других ключей в объекте конфигурации, шаблоны действуют как глобальные исключения и применяются к каждому объекту конфигурации.
• extends — массив строк, объектов конфигурации или массивов конфигураций, содержащих дополнительную конфигурацию для применения.
• language — строка, задающая язык, используемый для линтинга, в формате "pluginName/languageName", например "markdown/commonmark". (по умолчанию: "js/js" для JavaScript)
• 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").
  • reportUnusedInlineConfigs — строка уровня серьёзности, указывающая, следует ли отслеживать и сообщать о неиспользуемых встроенных конфигурациях и как это делать. (по умолчанию: "off")
• processor — либо объект, содержащий методы preprocess() и postprocess(), либо строка, указывающая имя процессора внутри плагина (например, "pluginName/processorName").
• plugins — объект, содержащий пары «имя-значение», которые связывают имена плагинов с объектами плагинов. Если задано files, эти плагины доступны только для соответствующих файлов.
• rules — объект, содержащий настроенные правила. Если заданы files или ignores, эти правила конфигурации доступны только для соответствующих файлов.
• settings — объект, содержащий пары «имя-значение» с информацией, доступной всем правилам.

Указание files и ignores

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

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
	// matches all files ending with .js
	{
		files: ["**/*.js"],
		rules: {
			semi: "error",
		},
	},

	// matches all files ending with .js except those in __tests
	{
		files: ["**/*.js"],
		ignores: ["__tests/**"],
		rules: {
			"no-console": "error",
		},
	},
]);

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

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
	// matches all files because it doesn't specify the `files` or `ignores` key
	{
		rules: {
			semi: "error",
		},
	},
]);

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

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

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

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
	{
		files: ["**/*.ts", "**/*.cts", "**/*.mts"],
	},
	// ...other config
]);

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

Файлы без расширения можно сопоставить с шаблоном !(*.*). Например:

// eslint.config.js
import { defineConfig } from "eslint/config";

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

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

Указание файлов с помощью операции И

Можно сопоставить один файл с несколькими шаблонами, используя массив строк внутри массива files. Например:

// eslint.config.js
import { defineConfig } from "eslint/config";

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

Шаблон ["src/*", "**/.js"] соответствует файлу, если он находится в каталоге src и заканчивается на .js. Такой подход может быть полезен, если вы динамически вычисляете значение массива files и хотите избежать возможных ошибок при попытке объединить несколько шаблонов glob в одну строку.

Исключение файлов с помощью ignores

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

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
	{
		files: ["src/**/*.js"],
		rules: {
			semi: "error",
		},
	},
]);

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

// eslint.config.js
import { defineConfig } from "eslint/config";

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

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

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
	{
		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. Например:

// eslint.config.js
import { defineConfig } from "eslint/config";

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

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

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

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

В зависимости от способа использования свойства ignores оно может действовать как неглобальное ignores или глобальное ignores.

• Если ignores используется без других ключей (кроме name) в объекте конфигурации, шаблоны действуют как глобальные исключения. Это означает, что они применяются ко всем объектам конфигурации, а не только к объекту, в котором они заданы. Глобальные ignores позволяют не копировать свойство ignores и не поддерживать его синхронизацию в нескольких объектах конфигурации.
• Если ignores используется вместе с другими свойствами в том же объекте конфигурации, шаблоны действуют как неглобальные исключения. В этом случае ignores применяется только к объекту конфигурации, в котором оно задано.

Глобальные и неглобальные ignores различаются в использовании:

• шаблоны в неглобальном ignores соответствуют только файлам (dir/filename.js) или файлам внутри каталогов (dir/**)
• шаблоны в глобальном ignores могут соответствовать каталогам (dir/), а также файлам и каталогам, поддерживаемым неглобальными исключениями.

Для всех вариантов использования ignores:

• Заданные вами шаблоны добавляются после шаблонов ESLint по умолчанию, то есть ["**/node_modules/", ".git/"].
• Шаблоны всегда соответствуют файлам и каталогам, начинающимся с точки, например .foo.js или .fixtures, если только эти файлы явно не исключены. Единственный каталог с точкой, игнорируемый по умолчанию, — .git.

// eslint.config.js
import { defineConfig } from "eslint/config";

// Example of global ignores
export default defineConfig([
    {
      ignores: [".config/", "dist/", "tsconfig.json"] // acts as global ignores, due to the absence of other properties
    },
    { ... }, // ... other configuration object, inherit global ignores
    { ... }, // ... other configuration object, inherit global ignores
]);

// Example of non-global ignores
export default defineConfig([
    {
      ignores: [".config/**", "dir1/script1.js"],
      rules: { ... } // the presence of this property dictates non-global ignores
    },
    {
      ignores: ["other-dir/**", "dist/script2.js"],
      rules: { ... } // the presence of this property dictates non-global ignores
    },
]);

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

// eslint.config.js
import { defineConfig, globalIgnores } from "eslint/config";

// Example of global ignores
export default defineConfig([
    globalIgnores([".config/", "dist/", "tsconfig.json"]),
    { ... }, // ... other configuration object, inherit global ignores
    { ... }, // ... other configuration object, inherit global ignores
]);

// Example of non-global ignores
export default defineConfig([
    {
      ignores: [".config/**", "dir1/script1.js"],
      rules: { ... } // the presence of this property dictates non-global ignores
    },
    {
      ignores: ["other-dir/**", "dist/script2.js"],
      rules: { ... } // the presence of this property dictates non-global ignores
    },
]);

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

Указание базового пути

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

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
	// matches all files in tests and its subdirectories
	{
		basePath: "tests",
		rules: {
			"no-undef": "error",
		},
	},

	// matches all files ending with spec.js in tests and its subdirectories
	{
		basePath: "tests",
		files: ["**/*.spec.js"],
		languageOptions: {
			globals: {
				it: "readonly",
				describe: "readonly",
			},
		},
	},

	// globally ignores tests/fixtures directory
	{
		basePath: "tests",
		ignores: ["fixtures/"],
	},
]);

В сочетании с extends к одному подкаталогу можно применить несколько объектов конфигурации, указав basePath только один раз, например:

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
	{
		basePath: "tests",
		extends: [
			// matches all files in tests and its subdirectories
			{
				rules: {
					"no-undef": "error",
				},
			},

			// matches all files ending with spec.js in tests and its subdirectories
			{
				files: ["**/*.spec.js"],
				languageOptions: {
					globals: {
						it: "readonly",
						describe: "readonly",
					},
				},
			},

			// globally ignores tests/fixtures directory
			{
				ignores: ["fixtures/"],
			},
		],
	},
]);

Последовательное применение объектов конфигурации

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

// eslint.config.js
import { defineConfig } from "eslint/config";

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

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

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

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

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

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

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
	{
		files: ["**/*.js"],
		linterOptions: {
			noInlineConfig: true,
		},
	},
]);

Сообщения о неиспользуемых директивах отключения

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

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
	{
		files: ["**/*.js"],
		linterOptions: {
			reportUnusedDisableDirectives: "error",
		},
	},
]);

По умолчанию для этого параметра задано "warn".

Переопределить этот параметр можно с помощью параметров командной строки --report-unused-disable-directives или --report-unused-disable-directives-severity.

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

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

Встроенные комментарии конфигурации, например /* eslint rule-name: "error" */, используются для изменения уровня серьёзности и/или параметров правил ESLint в определённых фрагментах кода. При изменении файла конфигурации ESLint проекта эти директивы могут перестать отличаться от уже заданных параметров. Чтобы сообщать о таких неиспользуемых встроенных комментариях конфигурации, задайте для параметра reportUnusedInlineConfigs строку уровня серьёзности, как в этом примере:

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
	{
		files: ["**/*.js"],
		linterOptions: {
			reportUnusedInlineConfigs: "error",
		},
	},
]);

Переопределить этот параметр можно с помощью параметра командной строки --report-unused-inline-configs.

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

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

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
	{
		rules: {
			semi: "error",
		},
	},
]);

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

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
	{
		rules: {
			semi: ["error", "never"],
		},
	},
]);

У каждого правила свой набор параметров; они могут иметь любой допустимый тип данных JSON. Сведения о доступных параметрах см. в документации правила, которое вы хотите настроить.

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

Настройка общих параметров

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

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
	{
		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",
		},
	},
]);

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

Объект конфигурации использует extends, чтобы унаследовать все свойства другого объекта конфигурации или массива (включая правила, плагины и параметры языка), а затем изменить любые параметры. Ключ extends — это массив значений, указывающих конфигурации, которые нужно расширить. Элементы массива extends могут иметь один из трёх видов:

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

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

Плагины ESLint могут экспортировать предопределённые конфигурации. На такие конфигурации ссылаются с помощью строки, соответствующей шаблону pluginName/configName. Сначала плагин нужно указать в ключе plugins. Вот пример:

// eslint.config.js
import examplePlugin from "eslint-plugin-example";
import { defineConfig } from "eslint/config";

export default defineConfig([
	{
		files: ["**/*.js"],
		plugins: {
			example: examplePlugin,
		},
		extends: ["example/recommended"],
	},
]);

В этом примере загружается конфигурация с именем recommended из eslint-plugin-example. На конфигурации плагинов также можно ссылаться по имени внутри массива конфигураций.

Можно также напрямую добавлять конфигурации плагинов в массив extends. Например:

// eslint.config.js
import pluginExample from "eslint-plugin-example";
import { defineConfig } from "eslint/config";

export default defineConfig([
	{
		files: ["**/*.js"],
		plugins: {
			example: pluginExample,
		},
		extends: [pluginExample.configs.recommended],
	},
]);

В этом случае конфигурация с именем recommended из eslint-plugin-example получается напрямую через свойство configs объекта плагина.

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

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

• js/recommended — включает правила, которые ESLint рекомендует использовать всем, чтобы избежать потенциальных ошибок.
• js/all — включает все правила, поставляемые вместе с ESLint. Эта конфигурация не рекомендуется для использования в производственной среде, поскольку она меняется с каждым минорным и мажорным выпуском ESLint. Используйте её на свой страх и риск.

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

// eslint.config.js
import js from "@eslint/js";
import { defineConfig } from "eslint/config";

export default defineConfig([
	{
		files: ["**/*.js"],
		plugins: {
			js,
		},
		extends: ["js/recommended"],
		rules: {
			"no-unused-vars": "warn",
		},
	},
]);

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

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

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

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

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

export default defineConfig([
	{
		files: ["**/*.js"],
		extends: [exampleConfig],
		rules: {
			"no-unused-vars": "warn",
		},
	},
]);

В этом примере exampleConfig может быть объектом или массивом; в любом случае его можно напрямую добавить в массив extends.

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

Когда использовать extends, а когда — последовательное применение

Когда следует использовать Extends:

• Для повторного использования конфигураций — когда нужно унаследовать существующие конфигурации плагинов, совместно используемых пакетов или предопределённых конфигураций и развить их.
• Для настройки плагинов — при применении рекомендуемых или специальных конфигураций плагинов ESLint (например, example/recommended).
• Для совместно используемых конфигураций — при использовании пакетов npm, экспортирующих объекты конфигурации (например, eslint-config-example).
• Для предопределённых конфигураций — при использовании встроенных конфигураций ESLint, таких как js/recommended или js/all.
• Для модульной конфигурации — когда нужно объединить несколько источников конфигурации в один объект конфигурации.
• Для обеспечения согласованности — когда нужно использовать согласованный набор базовых правил в нескольких объектах конфигурации.
• Для интеграции плагинов — когда нужно применить конфигурации, поставляемые вместе с плагинами.

Когда следует использовать Cascading:

• Для правил, зависящих от файлов — когда для разных шаблонов файлов или каталогов нужны разные правила.
• Для постепенной настройки — когда нужно применить базовые правила ко всем файлам, а затем добавить или переопределить правила для отдельных подмножеств.
• Для параметров, зависящих от среды — когда для тестовых файлов, исходных файлов и файлов конфигурации нужны разные наборы правил.
• Для настройки по каталогам — когда для разных каталогов проекта нужны разные подходы к линтингу.
• Для изменения уровня серьёзности правил — когда нужно изменить уровень серьёзности правила (error/warn/off) для определённых шаблонов файлов.
• Для разных параметров языка — когда для разных файлов нужны разные версии ECMAScript или параметры парсера.

Соглашения об именовании конфигураций

Свойство 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",
				files: ["src/**/*.js"],
				rules: {
					"no-unused-vars": "error",
				},
			},
		],
	},
};

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

При запуске ESLint из командной строки конфигурация для каждого целевого файла определяется так: сначала поиск выполняется в каталоге, содержащем файл, а затем — в родительских каталогах, пока не будет найден файл eslint.config.*. Такое поведение улучшает поддержку монорепозиториев, в подкаталогах которых могут находиться собственные файлы конфигурации.

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

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

yarn dlx eslint --config some-other-file.js **/*.js 

pnpm dlx eslint --config some-other-file.js **/*.js 

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

В этом случае ESLint не ищет файлы конфигурации, а вместо этого использует some-other-file.js.

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

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

npm install --save-dev jiti

yarn add --dev jiti

pnpm add --save-dev jiti

bun add --dev jiti

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

Встроенная поддержка TypeScript

Если вы используете Node.js >= 22.13.0, файлы конфигурации TypeScript можно загружать напрямую, без jiti. Это возможно благодаря флагу --experimental-strip-types.

Поскольку эта функция всё ещё является экспериментальной, необходимо также включить флаг unstable_native_nodejs_ts_config.

npx --node-options='--experimental-strip-types' eslint --flag unstable_native_nodejs_ts_config

Приоритет файлов конфигурации

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

1. eslint.config.js
2. eslint.config.mjs
3. eslint.config.cjs
4. eslint.config.ts
5. eslint.config.mts
6. eslint.config.cts

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

npx eslint --config eslint.config.ts 

yarn dlx eslint --config eslint.config.ts 

pnpm dlx eslint --config eslint.config.ts 

bunx eslint --config eslint.config.ts