eslint/docs/src/user-guide/configuring/plugins.md

   1 ---
   2 title: Plugins
   3 layout: doc
   4 eleventyNavigation:
   5     key: configuring plugins
   6     parent: configuring
   7     title: Configuring Plugins
   8     order: 4
   9
  10 ---
  11
  12 ## Specifying Parser
  13
  14 By default, ESLint uses [Espree](https://github.com/eslint/espree) as its parser. You can optionally specify that a different parser should be used in your configuration file so long as the parser meets the following requirements:
  15
  16 1. It must be a Node module loadable from the config file where the parser is used. Usually, this means you should install the parser package separately using npm.
  17 1. It must conform to the [parser interface](../../developer-guide/working-with-custom-parsers).
  18
  19 Note that even with these compatibilities, there are no guarantees that an external parser will work correctly with ESLint and ESLint will not fix bugs related to incompatibilities with other parsers.
  20
  21 To indicate the npm module to use as your parser, specify it using the `parser` option in your `.eslintrc` file. For example, the following specifies to use Esprima instead of Espree:
  22
  23 ```json
  24 {
  25     "parser": "esprima",
  26     "rules": {
  27         "semi": "error"
  28     }
  29 }
  30 ```
  31
  32 The following parsers are compatible with ESLint:
  33
  34 * [Esprima](https://www.npmjs.com/package/esprima)
  35 * [@babel/eslint-parser](https://www.npmjs.com/package/@babel/eslint-parser) - A wrapper around the [Babel](https://babeljs.io) parser that makes it compatible with ESLint.
  36 * [@typescript-eslint/parser](https://www.npmjs.com/package/@typescript-eslint/parser) - A parser that converts TypeScript into an ESTree-compatible form so it can be used in ESLint.
  37
  38 Note when using a custom parser, the `parserOptions` configuration property is still required for ESLint to work properly with features not in ECMAScript 5 by default. Parsers are all passed `parserOptions` and may or may not use them to determine which features to enable.
  39
  40 ## Specifying Processor
  41
  42 Plugins may provide processors. Processors can extract JavaScript code from other kinds of files, then let ESLint lint the JavaScript code or processors can convert JavaScript code in preprocessing for some purpose.
  43
  44 To specify processors in a configuration file, use the `processor` key with the concatenated string of a plugin name and a processor name by a slash. For example, the following enables the processor `a-processor` that the plugin `a-plugin` provided:
  45
  46 ```json
  47 {
  48     "plugins": ["a-plugin"],
  49     "processor": "a-plugin/a-processor"
  50 }
  51 ```
  52
  53 To specify processors for specific kinds of files, use the combination of the `overrides` key and the `processor` key. For example, the following uses the processor `a-plugin/markdown` for `*.md` files.
  54
  55 ```json
  56 {
  57     "plugins": ["a-plugin"],
  58     "overrides": [
  59         {
  60             "files": ["*.md"],
  61             "processor": "a-plugin/markdown"
  62         }
  63     ]
  64 }
  65 ```
  66
  67 Processors may make named code blocks such as `0.js` and `1.js`. ESLint handles such a named code block as a child file of the original file. You can specify additional configurations for named code blocks in the `overrides` section of the config. For example, the following disables the `strict` rule for the named code blocks which end with `.js` in markdown files.
  68
  69 ```json
  70 {
  71     "plugins": ["a-plugin"],
  72     "overrides": [
  73         {
  74             "files": ["*.md"],
  75             "processor": "a-plugin/markdown"
  76         },
  77         {
  78             "files": ["**/*.md/*.js"],
  79             "rules": {
  80                 "strict": "off"
  81             }
  82         }
  83     ]
  84 }
  85 ```
  86
  87 ESLint checks the file path of named code blocks then ignores those if any `overrides` entry didn't match the file path. Be sure to add an `overrides` entry if you want to lint named code blocks other than `*.js`.
  88
  89 ## Configuring Plugins
  90
  91 ESLint supports the use of third-party plugins. Before using the plugin, you have to install it using npm.
  92
  93 To configure plugins inside of a configuration file, use the `plugins` key, which contains a list of plugin names. The `eslint-plugin-` prefix can be omitted from the plugin name.
  94
  95 ```json
  96 {
  97     "plugins": [
  98         "plugin1",
  99         "eslint-plugin-plugin2"
 100     ]
 101 }
 102 ```
 103
 104 And in YAML:
 105
 106 ```yaml
 107 ---
 108   plugins:
 109     - plugin1
 110     - eslint-plugin-plugin2
 111 ```
 112
 113 **Notes:**
 114
 115 1. Plugins are resolved relative to the config file. In other words, ESLint will load the plugin as a user would obtain by running `require('eslint-plugin-pluginname')` in the config file.
 116 2. Plugins in the base configuration (loaded by `extends` setting) are relative to the derived config file. For example, if `./.eslintrc` has `extends: ["foo"]` and the `eslint-config-foo` has `plugins: ["bar"]`, ESLint finds the `eslint-plugin-bar` from `./node_modules/` (rather than `./node_modules/eslint-config-foo/node_modules/`) or ancestor directories. Thus every plugin in the config file and base configurations is resolved uniquely.
 117
 118 ### Naming convention
 119
 120 #### Include a plugin
 121
 122 The `eslint-plugin-` prefix can be omitted for non-scoped packages
 123
 124 ```js
 125 {
 126     // ...
 127     "plugins": [
 128         "jquery", // means eslint-plugin-jquery
 129     ]
 130     // ...
 131 }
 132 ```
 133
 134 The same rule does apply to scoped packages:
 135
 136 ```js
 137 {
 138     // ...
 139     "plugins": [
 140         "@jquery/jquery", // means @jquery/eslint-plugin-jquery
 141         "@foobar" // means @foobar/eslint-plugin
 142     ]
 143     // ...
 144 }
 145 ```
 146
 147 #### Use a plugin
 148
 149 When using rules, environments or configs defined by plugins, they must be referenced following the convention:
 150
 151 * `eslint-plugin-foo` → `foo/a-rule`
 152 * `@foo/eslint-plugin` → `@foo/a-config`
 153 * `@foo/eslint-plugin-bar` → `@foo/bar/a-environment`
 154
 155 For example:
 156
 157 ```js
 158 {
 159     // ...
 160     "plugins": [
 161         "jquery",   // eslint-plugin-jquery
 162         "@foo/foo", // @foo/eslint-plugin-foo
 163         "@bar"      // @bar/eslint-plugin
 164     ],
 165     "extends": [
 166         "plugin:@foo/foo/recommended",
 167         "plugin:@bar/recommended"
 168     ],
 169     "rules": {
 170         "jquery/a-rule": "error",
 171         "@foo/foo/some-rule": "error",
 172         "@bar/another-rule": "error"
 173     },
 174     "env": {
 175         "jquery/jquery": true,
 176         "@foo/foo/env-foo": true,
 177         "@bar/env-bar": true,
 178     }
 179     // ...
 180 }
 181 ```