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

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