From 88f99d31b88a4cde4563bc4a6f4c41f0cc557885 Mon Sep 17 00:00:00 2001 From: Kai Cataldo Date: Sat, 22 Dec 2018 17:55:48 -0500 Subject: [PATCH] Docs: clarify how to use configs in plugins (#11199) --- docs/developer-guide/working-with-plugins.md | 81 +++++++++++++------- 1 file changed, 53 insertions(+), 28 deletions(-) diff --git a/docs/developer-guide/working-with-plugins.md b/docs/developer-guide/working-with-plugins.md index 4d0ab55d5a6..83f107512d0 100644 --- a/docs/developer-guide/working-with-plugins.md +++ b/docs/developer-guide/working-with-plugins.md @@ -52,31 +52,33 @@ Plugin environments can define the following objects: You can also create plugins that would tell ESLint how to process files other than JavaScript. In order to create a processor, the object that is exported from your module has to conform to the following interface: ```js -processors: { +module.exports = { + processors: { - // assign to the file extension you want (.js, .jsx, .html, etc.) - ".ext": { - // takes text of the file and filename - preprocess: function(text, filename) { - // here, you can strip out any non-JS content - // and split into multiple strings to lint + // assign to the file extension you want (.js, .jsx, .html, etc.) + ".ext": { + // takes text of the file and filename + preprocess: function(text, filename) { + // here, you can strip out any non-JS content + // and split into multiple strings to lint - return [string]; // return an array of strings to lint - }, + return [string]; // return an array of strings to lint + }, - // takes a Message[][] and filename - postprocess: function(messages, filename) { - // `messages` argument contains two-dimensional array of Message objects - // where each top-level array item contains array of lint messages related - // to the text that was returned in array from preprocess() method + // takes a Message[][] and filename + postprocess: function(messages, filename) { + // `messages` argument contains two-dimensional array of Message objects + // where each top-level array item contains array of lint messages related + // to the text that was returned in array from preprocess() method - // you need to return a one-dimensional array of the messages you want to keep - return [Message]; - }, + // you need to return a one-dimensional array of the messages you want to keep + return messages[0]; + }, - supportsAutofix: true // (optional, defaults to false) + supportsAutofix: true // (optional, defaults to false) + } } -} +}; ``` The `preprocess` method takes the file contents and filename as arguments, and returns an array of strings to lint. The strings will be linted separately but still be registered to the filename. It's up to the plugin to decide if it needs to return just one part, or multiple pieces. For example in the case of processing `.html` files, you might want to return just one item in the array by combining all scripts, but for `.md` file where each JavaScript block might be independent, you can return multiple items. @@ -117,22 +119,45 @@ To support multiple extensions, add each one to the `processors` element and poi ### Configs in Plugins -You can bundle configurations inside a plugin. This can be useful when you want to provide not just code style, but also some custom rules to support it. You can specify configurations under `configs` key. Please note that when exposing configurations, you have to name each one, and there is no default. So your users will have to specify the name of the configuration they want to use. +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. ```js -configs: { - myConfig: { - env: ["browser"], - rules: { - semi: 2, - "myPlugin/my-rule": 2, - "eslint-plugin-myPlugin/another-rule": 2 +// eslint-plugin-myPlugin + +module.exports = { + configs: { + myConfig: { + plugins: ["myPlugin"], + env: ["browser"], + rules: { + semi: "error", + "myPlugin/my-rule": "error", + "eslint-plugin-myPlugin/another-rule": "error" + } + }, + myOtherConfig: { + plugins: ["myPlugin"], + env: ["node"], + rules: { + "myPlugin/my-rule": "off", + "eslint-plugin-myPlugin/another-rule": "off" + "eslint-plugin-myPlugin/yet-another-rule": "error" + } } } +}; +``` + +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. + +```json +{ + "extends": ["plugin:myPlugin/myConfig"] } + ``` -**Note:** Please note that configuration will not automatically attach your rules and you have to specify your plugin name and 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 [Configuring Plugins](../user-guide/configuring.md#configuring-plugins) +**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 [Configuring Plugins](../user-guide/configuring.md#configuring-plugins) for more information. ### Peer Dependency