eslint/docs/rules/no-unused-vars.md

   1 # Disallow Unused Variables (no-unused-vars)
   2
   3 Variables that are declared and not used anywhere in the code are most likely an error due to incomplete refactoring. Such variables take up space in the code and can lead to confusion by readers.
   4
   5 ## Rule Details
   6
   7 This rule is aimed at eliminating unused variables, functions, and function parameters.
   8
   9 A variable `foo` is considered to be used if any of the following are true:
  10
  11 * It is called (`foo()`) or constructed (`new foo()`)
  12 * It is read (`var bar = foo`)
  13 * It is passed into a function as an argument (`doSomething(foo)`)
  14 * It is read inside of a function that is passed to another function (`doSomething(function() { foo(); })`)
  15
  16 A variable is *not* considered to be used if it is only ever declared (`var foo = 5`) or assigned to (`foo = 7`).
  17
  18 Examples of **incorrect** code for this rule:
  19
  20 ```js
  21 /*eslint no-unused-vars: "error"*/
  22 /*global some_unused_var*/
  23
  24 // It checks variables you have defined as global
  25 some_unused_var = 42;
  26
  27 var x;
  28
  29 // Write-only variables are not considered as used.
  30 var y = 10;
  31 y = 5;
  32
  33 // A read for a modification of itself is not considered as used.
  34 var z = 0;
  35 z = z + 1;
  36
  37 // By default, unused arguments cause warnings.
  38 (function(foo) {
  39     return 5;
  40 })();
  41
  42 // Unused recursive functions also cause warnings.
  43 function fact(n) {
  44     if (n < 2) return 1;
  45     return n * fact(n - 1);
  46 }
  47
  48 // When a function definition destructures an array, unused entries from the array also cause warnings.
  49 function getY([x, y]) {
  50     return y;
  51 }
  52 ```
  53
  54 Examples of **correct** code for this rule:
  55
  56 ```js
  57 /*eslint no-unused-vars: "error"*/
  58
  59 var x = 10;
  60 alert(x);
  61
  62 // foo is considered used here
  63 myFunc(function foo() {
  64     // ...
  65 }.bind(this));
  66
  67 (function(foo) {
  68     return foo;
  69 })();
  70
  71 var myFunc;
  72 myFunc = setTimeout(function() {
  73     // myFunc is considered used
  74     myFunc();
  75 }, 50);
  76
  77 // Only the second argument from the destructured array is used.
  78 function getY([, y]) {
  79     return y;
  80 }
  81 ```
  82
  83 ### exported
  84
  85 In environments outside of CommonJS or ECMAScript modules, you may use `var` to create a global variable that may be used by other scripts. You can use the `/* exported variableName */` comment block to indicate that this variable is being exported and therefore should not be considered unused.
  86
  87 Note that `/* exported */` has no effect for any of the following:
  88
  89 * when the environment is `node` or `commonjs`
  90 * when `parserOptions.sourceType` is `module`
  91 * when `ecmaFeatures.globalReturn` is `true`
  92
  93 The line comment `// exported variableName` will not work as `exported` is not line-specific.
  94
  95 Examples of **correct** code for `/* exported variableName */` operation:
  96
  97 ```js
  98 /* exported global_var */
  99
 100 var global_var = 42;
 101 ```
 102
 103 ## Options
 104
 105 This rule takes one argument which can be a string or an object. The string settings are the same as those of the `vars` property (explained below).
 106
 107 By default this rule is enabled with `all` option for variables and `after-used` for arguments.
 108
 109 ```json
 110 {
 111     "rules": {
 112         "no-unused-vars": ["error", { "vars": "all", "args": "after-used", "ignoreRestSiblings": false }]
 113     }
 114 }
 115 ```
 116
 117 ### vars
 118
 119 The `vars` option has two settings:
 120
 121 * `all` checks all variables for usage, including those in the global scope. This is the default setting.
 122 * `local` checks only that locally-declared variables are used but will allow global variables to be unused.
 123
 124 #### vars: local
 125
 126 Examples of **correct** code for the `{ "vars": "local" }` option:
 127
 128 ```js
 129 /*eslint no-unused-vars: ["error", { "vars": "local" }]*/
 130 /*global some_unused_var */
 131
 132 some_unused_var = 42;
 133 ```
 134
 135 ### varsIgnorePattern
 136
 137 The `varsIgnorePattern` option specifies exceptions not to check for usage: variables whose names match a regexp pattern. For example, variables whose names contain `ignored` or `Ignored`.
 138
 139 Examples of **correct** code for the `{ "varsIgnorePattern": "[iI]gnored" }` option:
 140
 141 ```js
 142 /*eslint no-unused-vars: ["error", { "varsIgnorePattern": "[iI]gnored" }]*/
 143
 144 var firstVarIgnored = 1;
 145 var secondVar = 2;
 146 console.log(secondVar);
 147 ```
 148
 149 ### args
 150
 151 The `args` option has three settings:
 152
 153 * `after-used` - unused positional arguments that occur before the last used argument will not be checked, but all named arguments and all positional arguments after the last used argument will be checked.
 154 * `all` - all named arguments must be used.
 155 * `none` - do not check arguments.
 156
 157 #### args: after-used
 158
 159 Examples of **incorrect** code for the default `{ "args": "after-used" }` option:
 160
 161 ```js
 162 /*eslint no-unused-vars: ["error", { "args": "after-used" }]*/
 163
 164 // 2 errors, for the parameters after the last used parameter (bar)
 165 // "baz" is defined but never used
 166 // "qux" is defined but never used
 167 (function(foo, bar, baz, qux) {
 168     return bar;
 169 })();
 170 ```
 171
 172 Examples of **correct** code for the default `{ "args": "after-used" }` option:
 173
 174 ```js
 175 /*eslint no-unused-vars: ["error", {"args": "after-used"}]*/
 176
 177 (function(foo, bar, baz, qux) {
 178     return qux;
 179 })();
 180 ```
 181
 182 #### args: all
 183
 184 Examples of **incorrect** code for the `{ "args": "all" }` option:
 185
 186 ```js
 187 /*eslint no-unused-vars: ["error", { "args": "all" }]*/
 188
 189 // 2 errors
 190 // "foo" is defined but never used
 191 // "baz" is defined but never used
 192 (function(foo, bar, baz) {
 193     return bar;
 194 })();
 195 ```
 196
 197 #### args: none
 198
 199 Examples of **correct** code for the `{ "args": "none" }` option:
 200
 201 ```js
 202 /*eslint no-unused-vars: ["error", { "args": "none" }]*/
 203
 204 (function(foo, bar, baz) {
 205     return bar;
 206 })();
 207 ```
 208
 209 ### ignoreRestSiblings
 210
 211 The `ignoreRestSiblings` option is a boolean (default: `false`). Using a [Rest Property](https://github.com/tc39/proposal-object-rest-spread) it is possible to "omit" properties from an object, but by default the sibling properties are marked as "unused". With this option enabled the rest property's siblings are ignored.
 212
 213 Examples of **correct** code for the `{ "ignoreRestSiblings": true }` option:
 214
 215 ```js
 216 /*eslint no-unused-vars: ["error", { "ignoreRestSiblings": true }]*/
 217 // 'foo' and 'bar' were ignored because they have a rest property sibling.
 218 var { foo, ...coords } = data;
 219
 220 var bar;
 221 ({ bar, ...coords } = data);
 222 ```
 223
 224 ### argsIgnorePattern
 225
 226 The `argsIgnorePattern` option specifies exceptions not to check for usage: arguments whose names match a regexp pattern. For example, variables whose names begin with an underscore.
 227
 228 Examples of **correct** code for the `{ "argsIgnorePattern": "^_" }` option:
 229
 230 ```js
 231 /*eslint no-unused-vars: ["error", { "argsIgnorePattern": "^_" }]*/
 232
 233 function foo(x, _y) {
 234     return x + 1;
 235 }
 236 foo();
 237 ```
 238
 239 ### caughtErrors
 240
 241 The `caughtErrors` option is used for `catch` block arguments validation.
 242
 243 It has two settings:
 244
 245 * `none` - do not check error objects. This is the default setting.
 246 * `all` - all named arguments must be used.
 247
 248 #### caughtErrors: none
 249
 250 Not specifying this rule is equivalent of assigning it to `none`.
 251
 252 Examples of **correct** code for the `{ "caughtErrors": "none" }` option:
 253
 254 ```js
 255 /*eslint no-unused-vars: ["error", { "caughtErrors": "none" }]*/
 256
 257 try {
 258     //...
 259 } catch (err) {
 260     console.error("errors");
 261 }
 262 ```
 263
 264 #### caughtErrors: all
 265
 266 Examples of **incorrect** code for the `{ "caughtErrors": "all" }` option:
 267
 268 ```js
 269 /*eslint no-unused-vars: ["error", { "caughtErrors": "all" }]*/
 270
 271 // 1 error
 272 // "err" is defined but never used
 273 try {
 274     //...
 275 } catch (err) {
 276     console.error("errors");
 277 }
 278 ```
 279
 280 ### caughtErrorsIgnorePattern
 281
 282 The `caughtErrorsIgnorePattern` option specifies exceptions not to check for usage: catch arguments whose names match a regexp pattern. For example, variables whose names begin with a string 'ignore'.
 283
 284 Examples of **correct** code for the `{ "caughtErrorsIgnorePattern": "^ignore" }` option:
 285
 286 ```js
 287 /*eslint no-unused-vars: ["error", { "caughtErrorsIgnorePattern": "^ignore" }]*/
 288
 289 try {
 290     //...
 291 } catch (ignoreErr) {
 292     console.error("errors");
 293 }
 294 ```
 295
 296 ## When Not To Use It
 297
 298 If you don't want to be notified about unused variables or function arguments, you can safely turn this rule off.