diff --git a/docs/src/extend/custom-processors.md b/docs/src/extend/custom-processors.md index a2f1d805993..d2fd3df621d 100644 --- a/docs/src/extend/custom-processors.md +++ b/docs/src/extend/custom-processors.md @@ -2,9 +2,9 @@ title: Custom Processors eleventyNavigation: key: custom processors - parent: extend eslint + parent: create plugins title: Custom Processors - order: 5 + order: 2 --- You can also create custom processors that tell ESLint how to process files other than JavaScript. diff --git a/docs/src/extend/custom-rules.md b/docs/src/extend/custom-rules.md index cbb9be2d175..9c57dd1a122 100644 --- a/docs/src/extend/custom-rules.md +++ b/docs/src/extend/custom-rules.md @@ -2,9 +2,9 @@ title: Custom Rules eleventyNavigation: key: custom rules - parent: extend eslint + parent: create plugins title: Custom Rules - order: 3 + order: 1 --- diff --git a/docs/src/extend/plugins.md b/docs/src/extend/plugins.md index 6c063d599e0..f180c034faa 100644 --- a/docs/src/extend/plugins.md +++ b/docs/src/extend/plugins.md @@ -8,6 +8,10 @@ eleventyNavigation: --- +An ESLint plugin is an extension for ESLint that adds additional rules and configuration options. Plugins let you customize your ESLint configuration to enforce rules that are not included in the core ESLint package. Plugins can also provide additional environments, custom processors, and configurations. + +## Name a Plugin + Each plugin is an npm module with a name in the format of `eslint-plugin-`, such as `eslint-plugin-jquery`. You can also use scoped packages in the format of `@/eslint-plugin-` such as `@jquery/eslint-plugin-jquery` or even `@/eslint-plugin` such as `@jquery/eslint-plugin`. ## Create a Plugin @@ -16,7 +20,7 @@ The easiest way to start creating a plugin is to use the [Yeoman generator](http ### Rules in Plugins -Plugins can expose additional 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 (so it can just be `dollar-sign`, for instance). +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 (so it can just be `dollar-sign`, for instance). To learn more about creating custom rules in plugins, refer to [Custom Rules](custom-rules). ```js module.exports = { @@ -78,7 +82,9 @@ module.exports = { ### Configs in Plugins -You can bundle configurations inside a plugin by specifying them under the `configs` key. This can be useful when you want to provide not just code style, but also some custom rules to support it. Multiple configurations are supported per plugin. Note that it is not possible to specify a default configuration for a given plugin and that users must specify in their configuration file when they want to use one. +You can bundle configurations inside a plugin by specifying them under the `configs` key. This can be useful when you want to bundle a set of custom rules with additional configuration. Multiple configurations are supported per plugin. + +You can include individual rules from a plugin in a config that's also included in the plugin. In the config, you must specify your plugin name in the `plugins` array as well as any rules you want to enable that are part of the plugin. Any plugin rules must be prefixed with the short or long plugin name. ```js // eslint-plugin-myPlugin @@ -103,25 +109,33 @@ module.exports = { "eslint-plugin-myPlugin/yet-another-rule": "error" } } + }, + rules: { + "my-rule": {/* rule definition */}, + "another-rule": {/* rule definition */}, + "yet-another-rule": {/* rule definition */} } }; ``` -If the example plugin above were called `eslint-plugin-myPlugin`, the `myConfig` and `myOtherConfig` configurations would then be usable by extending off of `"plugin:myPlugin/myConfig"` and `"plugin:myPlugin/myOtherConfig"`, respectively. +Plugins cannot force a specific configuration to be used. Users must manually include a plugin's configurations in their configuration file. + +If the example plugin above were called `eslint-plugin-myPlugin`, the `myConfig` and `myOtherConfig` configurations would then be usable in a configuration file by extending `"plugin:myPlugin/myConfig"` and `"plugin:myPlugin/myOtherConfig"`, respectively. ```json +// .eslintrc.json + { "extends": ["plugin:myPlugin/myConfig"] } ``` -**Note:** Please note that configuration will not enable any of the plugin's rules by default, and instead should be treated as a standalone config. This means that you must specify your plugin name in the `plugins` array as well as any rules you want to enable that are part of the plugin. Any plugin rules must be prefixed with the short or long plugin name. See [Configure Plugins](../use/configure/plugins#configure-plugins) for more information. - ### Peer Dependency -To make clear that the plugin requires ESLint to work correctly you have to declare ESLint as a `peerDependency` in your `package.json`. -The plugin support was introduced in ESLint version `0.8.0`. Ensure the `peerDependency` points to ESLint `0.8.0` or later. +To make clear that the plugin requires ESLint to work correctly, you must declare ESLint as a peer dependency by mentioning it in the `peerDependencies` field of your plugin's `package.json`. + +Plugin support was introduced in ESLint version `0.8.0`. Ensure the `peerDependencies` points to ESLint `0.8.0` or later. ```json { @@ -131,11 +145,11 @@ The plugin support was introduced in ESLint version `0.8.0`. Ensure the `peerDep } ``` -### Testing +## Testing ESLint provides the [`RuleTester`](../integrate/nodejs-api#ruletester) utility to make it easy to test the rules of your plugin. -### Linting +## Linting ESLint plugins should be linted too! It's suggested to lint your plugin with the `recommended` configurations of: @@ -147,13 +161,7 @@ ESLint plugins should be linted too! It's suggested to lint your plugin with the In order to make your plugin available to the community you have to publish it on npm. -Recommended keywords: +To make it easy for others to find your plugin, add these [keywords](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#keywords) to your `package.json` file: * `eslint` * `eslintplugin` - -Add these keywords into your `package.json` file to make it easy for others to find. - -## Further Reading - -* [npm Developer Guide](https://docs.npmjs.com/misc/developers) diff --git a/docs/src/extend/shareable-configs.md b/docs/src/extend/shareable-configs.md index f22cb39b4cd..60b35321efd 100644 --- a/docs/src/extend/shareable-configs.md +++ b/docs/src/extend/shareable-configs.md @@ -4,7 +4,7 @@ eleventyNavigation: key: share configs parent: extend eslint title: Share Configurations - order: 6 + order: 3 --- diff --git a/docs/src/integrate/nodejs-api.md b/docs/src/integrate/nodejs-api.md index 08583fc3448..de035ca731c 100644 --- a/docs/src/integrate/nodejs-api.md +++ b/docs/src/integrate/nodejs-api.md @@ -4,7 +4,7 @@ eleventyNavigation: key: node.js api parent: extend eslint title: Node.js API Reference - order: 7 + order: 6 --- While ESLint is designed to be run on the command line, it's possible to use ESLint programmatically through the Node.js API. The purpose of the Node.js API is to allow plugin and tool authors to use the ESLint functionality directly, without going through the command line interface.