ESLint Compatibility Utilities

Overview

This packages contains functions that allow you to wrap existing ESLint rules, plugins, and configurations that were intended for use with ESLint v8.x to allow them to work as-is in ESLint v9.x.

Note: All plugins are not guaranteed to work in ESLint v9.x. This package fixes the most common issues but can't fix everything.

Installation

For Node.js and compatible runtimes:

1npm install @eslint/compat -D
2# or
3yarn add @eslint/compat -D
4# or
5pnpm install @eslint/compat -D
6# or
7bun add @eslint/compat -D

For Deno:

1deno add @eslint/compat

Usage

This package exports the following functions in both ESM and CommonJS format:

• fixupRule(rule) - wraps the given rule in a compatibility layer and returns the result
• fixupPluginRules(plugin) - wraps each rule in the given plugin using fixupRule() and returns a new object that represents the plugin with the fixed-up rules
• fixupConfigRules(configs) - wraps all plugins found in an array of config objects using fixupPluginRules()
• includeIgnoreFile(path) - reads an ignore file (like .gitignore) and converts the patterns into the correct format for the config file

Fixing Rules

If you have a rule that you'd like to make compatible with ESLint v9.x, you can do so using the fixupRule() function:

1// ESM example
2import { fixupRule } from "@eslint/compat";
3
4// Step 1: Import your rule
5import myRule from "./local-rule.js";
6
7// Step 2: Create backwards-compatible rule
8const compatRule = fixupRule(myRule);
9
10// Step 3 (optional): Export fixed rule
11export default compatRule;

Or in CommonJS:

1// CommonJS example
2const { fixupRule } = require("@eslint/compat");
3
4// Step 1: Import your rule
5const myRule = require("./local-rule.js");
6
7// Step 2: Create backwards-compatible rule
8const compatRule = fixupRule(myRule);
9
10// Step 3 (optional): Export fixed rule
11module.exports = compatRule;

Fixing Plugins

If you are using a plugin in your eslint.config.js that is not yet compatible with ESLint 9.x, you can wrap it using the fixupPluginRules() function:

1// eslint.config.js - ESM example
2import { fixupPluginRules } from "@eslint/compat";
3import somePlugin from "eslint-plugin-some-plugin";
4
5export default [
6	{
7		plugins: {
8			// insert the fixed plugin instead of the original
9			somePlugin: fixupPluginRules(somePlugin),
10		},
11		rules: {
12			"somePlugin/rule-name": "error",
13		},
14	},
15];

Or in CommonJS:

1// eslint.config.js - CommonJS example
2const { fixupPluginRules } = require("@eslint/compat");
3const somePlugin = require("eslint-plugin-some-plugin");
4
5module.exports = [
6	{
7		plugins: {
8			// insert the fixed plugin instead of the original
9			somePlugin: fixupPluginRules(somePlugin),
10		},
11		rules: {
12			"somePlugin/rule-name": "error",
13		},
14	},
15];

Fixing Configs

If you are importing other configs into your eslint.config.js that use plugins that are not yet compatible with ESLint 9.x, you can wrap the entire array or a single object using the fixupConfigRules() function:

1// eslint.config.js - ESM example
2import { fixupConfigRules } from "@eslint/compat";
3import someConfig from "eslint-config-some-config";
4
5export default [
6	...fixupConfigRules(someConfig),
7	{
8		// your overrides
9	},
10];

Or in CommonJS:

1// eslint.config.js - CommonJS example
2const { fixupConfigRules } = require("@eslint/compat");
3const someConfig = require("eslint-config-some-config");
4
5module.exports = [
6	...fixupConfigRules(someConfig),
7	{
8		// your overrides
9	},
10];

Including Ignore Files

If you were using an alternate ignore file in ESLint v8.x, such as using --ignore-path .gitignore on the command line, you can include those patterns programmatically in your config file using the includeIgnoreFile() function.

The includeIgnoreFile() function also accepts a second optional name parameter that allows you to set a custom name for this configuration object. If not specified, it defaults to "Imported .gitignore patterns". For example:

1// eslint.config.js - ESM example
2import { includeIgnoreFile } from "@eslint/compat";
3import path from "node:path";
4import { fileURLToPath } from "node:url";
5
6const __filename = fileURLToPath(import.meta.url);
7const __dirname = path.dirname(__filename);
8const gitignorePath = path.resolve(__dirname, ".gitignore");
9
10export default [
11	includeIgnoreFile(gitignorePath, "Imported .gitignore patterns"), // second argument is optional.
12	{
13		// your overrides
14	},
15];

Or in CommonJS:

1// eslint.config.js - CommonJS example
2const { includeIgnoreFile } = require("@eslint/compat");
3const path = require("node:path");
4const gitignorePath = path.resolve(__dirname, ".gitignore");
5
6module.exports = [
7	includeIgnoreFile(gitignorePath, "Imported .gitignore patterns"), // second argument is optional.
8	{
9		// your overrides
10	},
11];

Limitation: This works without modification when the ignore file is in the same directory as your config file. If the ignore file is in a different directory, you may need to modify the patterns manually.

License

Apache 2.0

Sponsors

The following companies, organizations, and individuals support ESLint's ongoing maintenance and development. Become a Sponsor to get your logo on our READMEs and website.

Diamond Sponsors

Platinum Sponsors

Gold Sponsors

Silver Sponsors

Bronze Sponsors

Technology Sponsors

Technology sponsors allow us to use their products and services for free as part of a contribution to the open source ecosystem and our work.