eslint/docs/developer-guide/working-with-plugins.md

   1 # Working with Plugins
   2
   3 Each plugin is an npm module with a name in the format of `eslint-plugin-<plugin-name>`, such as `eslint-plugin-jquery`. You can also use scoped packages in the format of `@<scope>/eslint-plugin-<plugin-name>` such as `@jquery/eslint-plugin-jquery` or even `@<scope>/eslint-plugin` such as `@jquery/eslint-plugin`.
   4
   5 ## Create a Plugin
   6
   7 The easiest way to start creating a plugin is to use the [Yeoman generator](https://www.npmjs.com/package/generator-eslint). The generator will guide you through setting up the skeleton of a plugin.
   8
   9 ### Rules in Plugins
  10
  11 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).
  12
  13 ```js
  14 module.exports = {
  15     rules: {
  16         "dollar-sign": {
  17             create: function (context) {
  18                 // rule implementation ...
  19             }
  20         }
  21     }
  22 };
  23 ```
  24
  25 To use the rule in ESLint, you would use the unprefixed plugin name, followed by a slash, followed by the rule name. So if this plugin were named `eslint-plugin-myplugin`, then in your configuration you'd refer to the rule by the name `myplugin/dollar-sign`. Example: `"rules": {"myplugin/dollar-sign": 2}`.
  26
  27 ### Environments in Plugins
  28
  29 Plugins can expose additional environments for use in ESLint. To do so, the plugin must export an `environments` object. The keys of the `environments` object are the names of the different environments provided and the values are the environment settings. For example:
  30
  31 ```js
  32 module.exports = {
  33     environments: {
  34         jquery: {
  35             globals: {
  36                 $: false
  37             }
  38         }
  39     }
  40 };
  41 ```
  42
  43 There's a `jquery` environment defined in this plugin. To use the environment in ESLint, you would use the unprefixed plugin name, followed by a slash, followed by the environment name. So if this plugin were named `eslint-plugin-myplugin`, then you would set the environment in your configuration to be `"myplugin/jquery"`.
  44
  45 Plugin environments can define the following objects:
  46
  47 1. `globals` - acts the same `globals` in a configuration file. The keys are the names of the globals and the values are `true` to allow the global to be overwritten and `false` to disallow.
  48 1. `parserOptions` - acts the same as `parserOptions` in a configuration file.
  49
  50 ### Processors in Plugins
  51
  52 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:
  53
  54 ```js
  55 module.exports = {
  56     processors: {
  57         "processor-name": {
  58             // takes text of the file and filename
  59             preprocess: function(text, filename) {
  60                 // here, you can strip out any non-JS content
  61                 // and split into multiple strings to lint
  62
  63                 return [ // return an array of code blocks to lint
  64                     { text: code1, filename: "0.js" },
  65                     { text: code2, filename: "1.js" },
  66                 ];
  67             },
  68
  69             // takes a Message[][] and filename
  70             postprocess: function(messages, filename) {
  71                 // `messages` argument contains two-dimensional array of Message objects
  72                 // where each top-level array item contains array of lint messages related
  73                 // to the text that was returned in array from preprocess() method
  74
  75                 // you need to return a one-dimensional array of the messages you want to keep
  76                 return [].concat(...messages);
  77             },
  78
  79             supportsAutofix: true // (optional, defaults to false)
  80         }
  81     }
  82 };
  83 ```
  84
  85 **The `preprocess` method** takes the file contents and filename as arguments, and returns an array of code blocks to lint. The code blocks will be linted separately but still be registered to the filename.
  86
  87 A code block has two properties `text` and `filename`; the `text` property is the content of the block and the `filename` property is the name of the block. Name of the block can be anything, but should include the file extension, that would tell the linter how to process the current block. The linter will check [`--ext` CLI option](../user-guide/command-line-interface.md#--ext) to see if the current block should be linted, and resolve `overrides` configs to check how to process the current block.
  88
  89 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.
  90
  91 **The `postprocess` method** takes a two-dimensional array of arrays of lint messages and the filename. Each item in the input array corresponds to the part that was returned from the `preprocess` method. The `postprocess` method must adjust the locations of all errors to correspond to locations in the original, unprocessed code, and aggregate them into a single flat array and return it.
  92
  93 Reported problems have the following location information:
  94
  95 ```typescript
  96 {
  97     line: number,
  98     column: number,
  99
 100     endLine?: number,
 101     endColumn?: number
 102 }
 103 ```
 104
 105 By default, ESLint will not perform autofixes when a processor is used, even when the `--fix` flag is enabled on the command line. To allow ESLint to autofix code when using your processor, you should take the following additional steps:
 106
 107 1. Update the `postprocess` method to additionally transform the `fix` property of reported problems. All autofixable problems will have a `fix` property, which is an object with the following schema:
 108
 109     ```js
 110     {
 111         range: [number, number],
 112         text: string
 113     }
 114     ```
 115
 116     The `range` property contains two indexes in the code, referring to the start and end location of a contiguous section of text that will be replaced. The `text` property refers to the text that will replace the given range.
 117
 118     In the initial list of problems, the `fix` property will refer to a fix in the processed JavaScript. The `postprocess` method should transform the object to refer to a fix in the original, unprocessed file.
 119
 120 2. Add a `supportsAutofix: true` property to the processor.
 121
 122 You can have both rules and processors in a single plugin. You can also have multiple processors in one plugin.
 123 To support multiple extensions, add each one to the `processors` element and point them to the same object.
 124
 125 #### Specifying Processor in Config Files
 126
 127 To use a processor, add its ID to a `processor` section in the config file. Processor ID is a concatenated string of plugin name and processor name with a slash as a separator. This can also be added to a `overrides` section of the config, to specify which processors should handle which files.
 128
 129 For example:
 130
 131 ```yml
 132 plugins:
 133   - a-plugin
 134 overrides:
 135   - files: "*.md"
 136     processor: a-plugin/markdown
 137 ```
 138
 139 See [Specifying Processor](../user-guide/configuring.md#specifying-processor) for details.
 140
 141 #### File Extension-named Processor
 142
 143 If a processor name starts with `.`, ESLint handles the processor as a **file extension-named processor** especially and applies the processor to the kind of files automatically. People don't need to specify the file extension-named processors in their config files.
 144
 145 For example:
 146
 147 ```js
 148 module.exports = {
 149     processors: {
 150         // This processor will be applied to `*.md` files automatically.
 151         // Also, people can use this processor as "plugin-id/.md" explicitly.
 152         ".md": {
 153             preprocess(text, filename) { /* ... */ },
 154             postprocess(messageLists, filename) { /* ... */ }
 155         }
 156     }
 157 }
 158 ```
 159
 160 ### Configs in Plugins
 161
 162 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.
 163
 164 ```js
 165 // eslint-plugin-myPlugin
 166
 167 module.exports = {
 168     configs: {
 169         myConfig: {
 170             plugins: ["myPlugin"],
 171             env: ["browser"],
 172             rules: {
 173                 semi: "error",
 174                 "myPlugin/my-rule": "error",
 175                 "eslint-plugin-myPlugin/another-rule": "error"
 176             }
 177         },
 178         myOtherConfig: {
 179             plugins: ["myPlugin"],
 180             env: ["node"],
 181             rules: {
 182                 "myPlugin/my-rule": "off",
 183                 "eslint-plugin-myPlugin/another-rule": "off"
 184                 "eslint-plugin-myPlugin/yet-another-rule": "error"
 185             }
 186         }
 187     }
 188 };
 189 ```
 190
 191 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.
 192
 193 ```json
 194 {
 195     "extends": ["plugin:myPlugin/myConfig"]
 196 }
 197
 198 ```
 199
 200 **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.
 201
 202 ### Peer Dependency
 203
 204 To make clear that the plugin requires ESLint to work correctly you have to declare ESLint as a `peerDependency` in your `package.json`.
 205 The plugin support was introduced in ESLint version `0.8.0`. Ensure the `peerDependency` points to ESLint `0.8.0` or later.
 206
 207 ```json
 208 {
 209     "peerDependencies": {
 210         "eslint": ">=0.8.0"
 211     }
 212 }
 213 ```
 214
 215 ### Testing
 216
 217 ESLint provides the [`RuleTester`](/docs/developer-guide/nodejs-api.md#ruletester) utility to make it easy to test the rules of your plugin.
 218
 219 ## Share Plugins
 220
 221 In order to make your plugin available to the community you have to publish it on npm.
 222
 223 Recommended keywords:
 224
 225 * `eslint`
 226 * `eslintplugin`
 227
 228 Add these keywords into your `package.json` file to make it easy for others to find.
 229
 230 ## Further Reading
 231
 232 * [npm Developer Guide](https://docs.npmjs.com/misc/developers)