Create Plugins

ESLint plugins extend ESLint with additional functionality. In most cases, you’ll extend ESLint by creating plugins that encapsulate the additional functionality you want to share across multiple projects.

Create a plugin

A plugin is a JavaScript object that exposes certain properties to ESLint:

• meta - information about the plugin.
• configs - an object containing named configurations.
• rules - an object containing the definitions of custom rules.
• processors - an object containing named processors.

To get started, create a JavaScript file and export an object containing the properties you’d like ESLint to use. To make your plugin as easy to maintain as possible, we recommend that you format your plugin entrypoint file to look like this:

const plugin = {
	meta: {},
	configs: {},
	rules: {},
	processors: {},
};

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;
1
2
3
4
5
6
7
8
9
10
11
12

If you plan to distribute your plugin as an npm package, make sure that the module that exports the plugin object is the default export of your package. This will enable ESLint to import the plugin when it is specified in the command line in the --plugin option.

Meta Data in Plugins

For easier debugging and more effective caching of plugins, it’s recommended to provide a name, version, and namespace in a meta object at the root of your plugin, like this:

const plugin = {
	// preferred location of name and version
	meta: {
		name: "eslint-plugin-example",
		version: "1.2.3",
		namespace: "example",
	},
	rules: {
		// add rules here
	},
};

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

The meta.name property should match the npm package name for your plugin and the meta.version property should match the npm package version for your plugin. The meta.namespace property should match the prefix you’d like users to use for accessing the plugin’s rules, processors, languages, and configs. The namespace is typically what comes after eslint-plugin- in your package name, which is why this example uses "example". Providing a namespace allows the defineConfig() function to find your plugin even when a user assigns a different namespace in their config file.

The easiest way to add the name and version is by reading this information from your package.json, as in this example:

import fs from "fs";

const pkg = JSON.parse(
	fs.readFileSync(new URL("./package.json", import.meta.url), "utf8"),
);

const plugin = {
	// preferred location of name and version
	meta: {
		name: pkg.name,
		version: pkg.version,
		namespace: "example",
	},
	rules: {
		// add rules here
	},
};

export default plugin;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

As an alternative, you can also expose name and version properties at the root of your plugin, such as:

const plugin = {
	// alternate location of name and version
	name: "eslint-plugin-example",
	version: "1.2.3",
	rules: {
		// add rules here
	},
};

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;
1
2
3
4
5
6
7
8
9
10
11
12
13
14

Rules in Plugins

Plugins can expose custom rules for use in ESLint. To do so, the plugin must export a rules object containing a key-value mapping of rule ID to rule. The rule ID does not have to follow any naming convention except that it should not contain a / character (so it can just be dollar-sign but not foo/dollar-sign, for instance). To learn more about creating custom rules in plugins, refer to Custom Rules.

const plugin = {
	meta: {
		name: "eslint-plugin-example",
		version: "1.2.3",
	},
	rules: {
		"dollar-sign": {
			create(context) {
				// rule implementation ...
			},
		},
	},
};

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin