eslint/docs/src/rules/sort-imports.md

   1 ---
   2 title: sort-imports
   3 rule_type: suggestion
   4 related_rules:
   5 - sort-keys
   6 - sort-vars
   7 ---
   8
   9
  10
  11 The import statement is used to import members (functions, objects or primitives) that have been exported from an external module. Using a specific member syntax:
  12
  13 ```js
  14 // single - Import single member.
  15 import myMember from "my-module.js";
  16 import {myOtherMember} from "my-other-module.js";
  17
  18 // multiple - Import multiple members.
  19 import {foo, bar} from "my-module.js";
  20
  21 // all - Import all members, where myModule contains all the exported bindings.
  22 import * as myModule from "my-module.js";
  23 ```
  24
  25 The import statement can also import a module without exported bindings. Used when the module does not export anything, but runs it own code or changes the global context object.
  26
  27 ```js
  28 // none - Import module without exported bindings.
  29 import "my-module.js"
  30 ```
  31
  32 When declaring multiple imports, a sorted list of import declarations make it easier for developers to read the code and find necessary imports later. This rule is purely a matter of style.
  33
  34 ## Rule Details
  35
  36 This rule checks all import declarations and verifies that all imports are first sorted by the used member syntax and then alphabetically by the first member or alias name.
  37
  38 The `--fix` option on the command line automatically fixes some problems reported by this rule: multiple members on a single line are automatically sorted (e.g. `import { b, a } from 'foo.js'` is corrected to `import { a, b } from 'foo.js'`), but multiple lines are not reordered.
  39
  40 ## Options
  41
  42 This rule accepts an object with its properties as
  43
  44 * `ignoreCase` (default: `false`)
  45 * `ignoreDeclarationSort` (default: `false`)
  46 * `ignoreMemberSort` (default: `false`)
  47 * `memberSyntaxSortOrder` (default: `["none", "all", "multiple", "single"]`); all 4 items must be present in the array, but you can change the order:
  48     * `none` = import module without exported bindings.
  49     * `all` = import all members provided by exported bindings.
  50     * `multiple` = import multiple members.
  51     * `single` = import single member.
  52 * `allowSeparatedGroups` (default: `false`)
  53
  54 Default option settings are:
  55
  56 ```json
  57 {
  58     "sort-imports": ["error", {
  59         "ignoreCase": false,
  60         "ignoreDeclarationSort": false,
  61         "ignoreMemberSort": false,
  62         "memberSyntaxSortOrder": ["none", "all", "multiple", "single"],
  63         "allowSeparatedGroups": false
  64     }]
  65 }
  66 ```
  67
  68 ## Examples
  69
  70 ### Default settings
  71
  72 Examples of **correct** code for this rule when using default options:
  73
  74 ::: correct
  75
  76 ```js
  77 /*eslint sort-imports: "error"*/
  78 import 'module-without-export.js';
  79 import * as bar from 'bar.js';
  80 import * as foo from 'foo.js';
  81 import {alpha, beta} from 'alpha.js';
  82 import {delta, gamma} from 'delta.js';
  83 import a from 'baz.js';
  84 import {b} from 'qux.js';
  85
  86 /*eslint sort-imports: "error"*/
  87 import a from 'foo.js';
  88 import b from 'bar.js';
  89 import c from 'baz.js';
  90
  91 /*eslint sort-imports: "error"*/
  92 import 'foo.js'
  93 import * as bar from 'bar.js';
  94 import {a, b} from 'baz.js';
  95 import c from 'qux.js';
  96 import {d} from 'quux.js';
  97
  98 /*eslint sort-imports: "error"*/
  99 import {a, b, c} from 'foo.js'
 100 ```
 101
 102 :::
 103
 104 Examples of **incorrect** code for this rule when using default options:
 105
 106 ::: incorrect
 107
 108 ```js
 109 /*eslint sort-imports: "error"*/
 110 import b from 'foo.js';
 111 import a from 'bar.js';
 112
 113 /*eslint sort-imports: "error"*/
 114 import a from 'foo.js';
 115 import A from 'bar.js';
 116
 117 /*eslint sort-imports: "error"*/
 118 import {b, c} from 'foo.js';
 119 import {a, b} from 'bar.js';
 120
 121 /*eslint sort-imports: "error"*/
 122 import a from 'foo.js';
 123 import {b, c} from 'bar.js';
 124
 125 /*eslint sort-imports: "error"*/
 126 import {a} from 'foo.js';
 127 import {b, c} from 'bar.js';
 128
 129 /*eslint sort-imports: "error"*/
 130 import a from 'foo.js';
 131 import * as b from 'bar.js';
 132
 133 /*eslint sort-imports: "error"*/
 134 import {b, a, c} from 'foo.js'
 135 ```
 136
 137 :::
 138
 139 ### `ignoreCase`
 140
 141 When `true` the rule ignores the case-sensitivity of the imports local name.
 142
 143 Examples of **incorrect** code for this rule with the `{ "ignoreCase": true }` option:
 144
 145 ::: incorrect
 146
 147 ```js
 148 /*eslint sort-imports: ["error", { "ignoreCase": true }]*/
 149
 150 import B from 'foo.js';
 151 import a from 'bar.js';
 152 ```
 153
 154 :::
 155
 156 Examples of **correct** code for this rule with the `{ "ignoreCase": true }` option:
 157
 158 ::: correct
 159
 160 ```js
 161 /*eslint sort-imports: ["error", { "ignoreCase": true }]*/
 162
 163 import a from 'foo.js';
 164 import B from 'bar.js';
 165 import c from 'baz.js';
 166 ```
 167
 168 :::
 169
 170 Default is `false`.
 171
 172 ### `ignoreDeclarationSort`
 173
 174 Ignores the sorting of import declaration statements.
 175
 176 Examples of **incorrect** code for this rule with the default `{ "ignoreDeclarationSort": false }` option:
 177
 178 ::: incorrect
 179
 180 ```js
 181 /*eslint sort-imports: ["error", { "ignoreDeclarationSort": false }]*/
 182 import b from 'foo.js'
 183 import a from 'bar.js'
 184 ```
 185
 186 :::
 187
 188 Examples of **correct** code for this rule with the `{ "ignoreDeclarationSort": true }` option:
 189
 190 ::: correct
 191
 192 ```js
 193 /*eslint sort-imports: ["error", { "ignoreDeclarationSort": true }]*/
 194 import a from 'foo.js'
 195 import b from 'bar.js'
 196 ```
 197
 198 :::
 199
 200 ::: correct
 201
 202 ```js
 203 /*eslint sort-imports: ["error", { "ignoreDeclarationSort": true }]*/
 204 import b from 'foo.js'
 205 import a from 'bar.js'
 206 ```
 207
 208 :::
 209
 210 Default is `false`.
 211
 212 ### `ignoreMemberSort`
 213
 214 Ignores the member sorting within a `multiple` member import declaration.
 215
 216 Examples of **incorrect** code for this rule with the default `{ "ignoreMemberSort": false }` option:
 217
 218 ::: incorrect
 219
 220 ```js
 221 /*eslint sort-imports: ["error", { "ignoreMemberSort": false }]*/
 222 import {b, a, c} from 'foo.js'
 223 ```
 224
 225 :::
 226
 227 Examples of **correct** code for this rule with the `{ "ignoreMemberSort": true }` option:
 228
 229 ::: correct
 230
 231 ```js
 232 /*eslint sort-imports: ["error", { "ignoreMemberSort": true }]*/
 233 import {b, a, c} from 'foo.js'
 234 ```
 235
 236 :::
 237
 238 Default is `false`.
 239
 240 ### `memberSyntaxSortOrder`
 241
 242 There are four different styles and the default member syntax sort order is:
 243
 244 * `none` - import module without exported bindings.
 245 * `all` - import all members provided by exported bindings.
 246 * `multiple` - import multiple members.
 247 * `single` - import single member.
 248
 249 All four options must be specified in the array, but you can customize their order.
 250
 251 Examples of **incorrect** code for this rule with the default `{ "memberSyntaxSortOrder": ["none", "all", "multiple", "single"] }` option:
 252
 253 ::: incorrect
 254
 255 ```js
 256 /*eslint sort-imports: "error"*/
 257 import a from 'foo.js';
 258 import * as b from 'bar.js';
 259 ```
 260
 261 :::
 262
 263 Examples of **correct** code for this rule with the `{ "memberSyntaxSortOrder": ['single', 'all', 'multiple', 'none'] }` option:
 264
 265 ::: correct
 266
 267 ```js
 268 /*eslint sort-imports: ["error", { "memberSyntaxSortOrder": ['single', 'all', 'multiple', 'none'] }]*/
 269
 270 import a from 'foo.js';
 271 import * as b from 'bar.js';
 272 ```
 273
 274 :::
 275
 276 Examples of **correct** code for this rule with the `{ "memberSyntaxSortOrder": ['all', 'single', 'multiple', 'none'] }` option:
 277
 278 ::: correct
 279
 280 ```js
 281 /*eslint sort-imports: ["error", { "memberSyntaxSortOrder": ['all', 'single', 'multiple', 'none'] }]*/
 282
 283 import * as foo from 'foo.js';
 284 import z from 'zoo.js';
 285 import {a, b} from 'foo.js';
 286 ```
 287
 288 :::
 289
 290 Default is `["none", "all", "multiple", "single"]`.
 291
 292 ### `allowSeparatedGroups`
 293
 294 When `true` the rule checks the sorting of import declaration statements only for those that appear on consecutive lines.
 295
 296 In other words, a blank line or a comment line or line with any other statement after an import declaration statement will reset the sorting of import declaration statements.
 297
 298 Examples of **incorrect** code for this rule with the `{ "allowSeparatedGroups": true }` option:
 299
 300 ::: incorrect
 301
 302 ```js
 303 /*eslint sort-imports: ["error", { "allowSeparatedGroups": true }]*/
 304
 305 import b from 'foo.js';
 306 import c from 'bar.js';
 307 import a from 'baz.js';
 308 ```
 309
 310 :::
 311
 312 Examples of **correct** code for this rule with the `{ "allowSeparatedGroups": true }` option:
 313
 314 ::: correct
 315
 316 ```js
 317 /*eslint sort-imports: ["error", { "allowSeparatedGroups": true }]*/
 318
 319 import b from 'foo.js';
 320 import c from 'bar.js';
 321
 322 import a from 'baz.js';
 323 ```
 324
 325 :::
 326
 327 ::: correct
 328
 329 ```js
 330 /*eslint sort-imports: ["error", { "allowSeparatedGroups": true }]*/
 331
 332 import b from 'foo.js';
 333 import c from 'bar.js';
 334 // comment
 335 import a from 'baz.js';
 336 ```
 337
 338 :::
 339
 340 ::: correct
 341
 342 ```js
 343 /*eslint sort-imports: ["error", { "allowSeparatedGroups": true }]*/
 344
 345 import b from 'foo.js';
 346 import c from 'bar.js';
 347 quux();
 348 import a from 'baz.js';
 349 ```
 350
 351 :::
 352
 353 Default is `false`.
 354
 355 ## When Not To Use It
 356
 357 This rule is a formatting preference and not following it won't negatively affect the quality of your code. If alphabetizing imports isn't a part of your coding standards, then you can leave this rule disabled.