eslint/docs/user-guide/configuring/rules.md

   1 # Rules
   2
   3 * [Configuring Rules](#configuring-rules)
   4 * [Disabling Rules](#disabling-rules)
   5
   6 ## Configuring Rules
   7
   8 ESLint comes with a large number of built-in rules and you can add more rules through plugins. You can modify which rules your project uses either using configuration comments or configuration files. To change a rule setting, you must set the rule ID equal to one of these values:
   9
  10 * `"off"` or `0` - turn the rule off
  11 * `"warn"` or `1` - turn the rule on as a warning (doesn't affect exit code)
  12 * `"error"` or `2` - turn the rule on as an error (exit code is 1 when triggered)
  13
  14 ### Using configuration comments
  15
  16 To configure rules inside of a file using configuration comments, use a comment in the following format:
  17
  18 ```js
  19 /* eslint eqeqeq: "off", curly: "error" */
  20 ```
  21
  22 In this example, [`eqeqeq`](https://eslint.org/docs/rules/eqeqeq) is turned off and [`curly`](https://eslint.org/docs/rules/curly) is turned on as an error. You can also use the numeric equivalent for the rule severity:
  23
  24 ```js
  25 /* eslint eqeqeq: 0, curly: 2 */
  26 ```
  27
  28 This example is the same as the last example, only it uses the numeric codes instead of the string values. The `eqeqeq` rule is off and the `curly` rule is set to be an error.
  29
  30 If a rule has additional options, you can specify them using array literal syntax, such as:
  31
  32 ```js
  33 /* eslint quotes: ["error", "double"], curly: 2 */
  34 ```
  35
  36 This comment specifies the "double" option for the [`quotes`](https://eslint.org/docs/rules/quotes) rule. The first item in the array is always the rule severity (number or string).
  37
  38 Configuration comments can include descriptions to explain why the comment is necessary. The description must occur after the configuration and is separated from the configuration by two or more consecutive `-` characters. For example:
  39
  40 ```js
  41 /* eslint eqeqeq: "off", curly: "error" -- Here's a description about why this configuration is necessary. */
  42 ```
  43
  44 ```js
  45 /* eslint eqeqeq: "off", curly: "error"
  46     --------
  47     Here's a description about why this configuration is necessary. */
  48 ```
  49
  50 ```js
  51 /* eslint eqeqeq: "off", curly: "error"
  52  * --------
  53  * This will not work due to the line above starting with a '*' character.
  54  */
  55 ```
  56
  57 ### Using configuration files
  58
  59 To configure rules inside of a configuration file, use the `rules` key along with an error level and any options you want to use. For example:
  60
  61 ```json
  62 {
  63     "rules": {
  64         "eqeqeq": "off",
  65         "curly": "error",
  66         "quotes": ["error", "double"]
  67     }
  68 }
  69 ```
  70
  71 And in YAML:
  72
  73 ```yaml
  74 ---
  75 rules:
  76   eqeqeq: off
  77   curly: error
  78   quotes:
  79     - error
  80     - double
  81 ```
  82
  83 To configure a rule which is defined within a plugin you have to prefix the rule ID with the plugin name and a `/`. For example:
  84
  85 ```json
  86 {
  87     "plugins": [
  88         "plugin1"
  89     ],
  90     "rules": {
  91         "eqeqeq": "off",
  92         "curly": "error",
  93         "quotes": ["error", "double"],
  94         "plugin1/rule1": "error"
  95     }
  96 }
  97 ```
  98
  99 And in YAML:
 100
 101 ```yaml
 102 ---
 103 plugins:
 104   - plugin1
 105 rules:
 106   eqeqeq: 0
 107   curly: error
 108   quotes:
 109     - error
 110     - "double"
 111   plugin1/rule1: error
 112 ```
 113
 114 In these configuration files, the rule `plugin1/rule1` comes from the plugin named `plugin1`. You can also use this format with configuration comments, such as:
 115
 116 ```js
 117 /* eslint "plugin1/rule1": "error" */
 118 ```
 119
 120 **Note:** When specifying rules from plugins, make sure to omit `eslint-plugin-`. ESLint uses only the unprefixed name internally to locate rules.
 121
 122 ## Disabling Rules
 123
 124 ### Using configuration comments
 125
 126 To temporarily disable rule warnings in your file, use block comments in the following format:
 127
 128 ```js
 129 /* eslint-disable */
 130
 131 alert('foo');
 132
 133 /* eslint-enable */
 134 ```
 135
 136 You can also disable or enable warnings for specific rules:
 137
 138 ```js
 139 /* eslint-disable no-alert, no-console */
 140
 141 alert('foo');
 142 console.log('bar');
 143
 144 /* eslint-enable no-alert, no-console */
 145 ```
 146
 147 To disable rule warnings in an entire file, put a `/* eslint-disable */` block comment at the top of the file:
 148
 149 ```js
 150 /* eslint-disable */
 151
 152 alert('foo');
 153 ```
 154
 155 You can also disable or enable specific rules for an entire file:
 156
 157 ```js
 158 /* eslint-disable no-alert */
 159
 160 alert('foo');
 161 ```
 162
 163 To disable all rules on a specific line, use a line or block comment in one of the following formats:
 164
 165 ```js
 166 alert('foo'); // eslint-disable-line
 167
 168 // eslint-disable-next-line
 169 alert('foo');
 170
 171 /* eslint-disable-next-line */
 172 alert('foo');
 173
 174 alert('foo'); /* eslint-disable-line */
 175 ```
 176
 177 To disable a specific rule on a specific line:
 178
 179 ```js
 180 alert('foo'); // eslint-disable-line no-alert
 181
 182 // eslint-disable-next-line no-alert
 183 alert('foo');
 184
 185 alert('foo'); /* eslint-disable-line no-alert */
 186
 187 /* eslint-disable-next-line no-alert */
 188 alert('foo');
 189 ```
 190
 191 To disable multiple rules on a specific line:
 192
 193 ```js
 194 alert('foo'); // eslint-disable-line no-alert, quotes, semi
 195
 196 // eslint-disable-next-line no-alert, quotes, semi
 197 alert('foo');
 198
 199 alert('foo'); /* eslint-disable-line no-alert, quotes, semi */
 200
 201 /* eslint-disable-next-line no-alert, quotes, semi */
 202 alert('foo');
 203 ```
 204
 205 All of the above methods also work for plugin rules. For example, to disable `eslint-plugin-example`'s `rule-name` rule, combine the plugin's name (`example`) and the rule's name (`rule-name`) into `example/rule-name`:
 206
 207 ```js
 208 foo(); // eslint-disable-line example/rule-name
 209 foo(); /* eslint-disable-line example/rule-name */
 210 ```
 211
 212 Configuration comments can include descriptions to explain why the comment is necessary. The description must come after the configuration and needs to be separated from the configuration by two or more consecutive `-` characters. For example:
 213
 214 ```js
 215 // eslint-disable-next-line no-console -- Here's a description about why this configuration is necessary.
 216 console.log('hello');
 217 ```
 218
 219 **Note:** Comments that disable warnings for a portion of a file tell ESLint not to report rule violations for the disabled code. ESLint still parses the entire file, however, so disabled code still needs to be syntactically valid JavaScript.
 220
 221 ### Using configuration files
 222
 223 To disable rules inside of a configuration file for a group of files, use the `overrides` key along with a `files` key. For example:
 224
 225 ```json
 226 {
 227   "rules": {...},
 228   "overrides": [
 229     {
 230       "files": ["*-test.js","*.spec.js"],
 231       "rules": {
 232         "no-unused-expressions": "off"
 233       }
 234     }
 235   ]
 236 }
 237 ```
 238
 239 ### Disabling Inline Comments
 240
 241 To disable all inline config comments, use the `noInlineConfig` setting. For example:
 242
 243 ```json
 244 {
 245   "rules": {...},
 246   "noInlineConfig": true
 247 }
 248 ```
 249
 250 This setting is similar to [--no-inline-config](https://eslint.org/docs/user-guide/command-line-interface#--no-inline-config) CLI option.
 251
 252 #### Report unused `eslint-disable` comments
 253
 254 To report unused `eslint-disable` comments, use the `reportUnusedDisableDirectives` setting. For example:
 255
 256 ```json
 257 {
 258   "rules": {...},
 259   "reportUnusedDisableDirectives": true
 260 }
 261 ```
 262
 263 This setting is similar to [--report-unused-disable-directives](https://eslint.org/docs/user-guide/command-line-interface#--report-unused-disable-directives) CLI option, but doesn't fail linting (reports as `"warn"` severity).