eslint/docs/rules/sort-imports.md

   1 # Import Sorting (sort-imports)
   2
   3 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:
   4
   5 ```js
   6 // single - Import single member.
   7 import myMember from "my-module.js";
   8
   9 // multiple - Import multiple members.
  10 import {foo, bar} from "my-module.js";
  11
  12 // all - Import all members, where myModule contains all the exported bindings.
  13 import * as myModule from "my-module.js";
  14 ```
  15
  16 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.
  17
  18 ```js
  19 // none - Import module without exported bindings.
  20 import "my-module.js"
  21 ```
  22
  23 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.
  24
  25 ## Rule Details
  26
  27 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.
  28
  29 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.
  30
  31 ## Options
  32
  33 This rule accepts an object with its properties as
  34
  35 * `ignoreCase` (default: `false`)
  36 * `ignoreDeclarationSort` (default: `false`)
  37 * `ignoreMemberSort` (default: `false`)
  38 * `memberSyntaxSortOrder` (default: `["none", "all", "multiple", "single"]`); all 4 items must be present in the array, but you can change the order:
  39     * `none` = import module without exported bindings.
  40     * `all` = import all members provided by exported bindings.
  41     * `multiple` = import multiple members.
  42     * `single` = import single member.
  43 * `allowSeparatedGroups` (default: `false`)
  44
  45 Default option settings are:
  46
  47 ```json
  48 {
  49     "sort-imports": ["error", {
  50         "ignoreCase": false,
  51         "ignoreDeclarationSort": false,
  52         "ignoreMemberSort": false,
  53         "memberSyntaxSortOrder": ["none", "all", "multiple", "single"],
  54         "allowSeparatedGroups": false
  55     }]
  56 }
  57 ```
  58
  59 ## Examples
  60
  61 ### Default settings
  62
  63 Examples of **correct** code for this rule when using default options:
  64
  65 ```js
  66 /*eslint sort-imports: "error"*/
  67 import 'module-without-export.js';
  68 import * as bar from 'bar.js';
  69 import * as foo from 'foo.js';
  70 import {alpha, beta} from 'alpha.js';
  71 import {delta, gamma} from 'delta.js';
  72 import a from 'baz.js';
  73 import b from 'qux.js';
  74
  75 /*eslint sort-imports: "error"*/
  76 import a from 'foo.js';
  77 import b from 'bar.js';
  78 import c from 'baz.js';
  79
  80 /*eslint sort-imports: "error"*/
  81 import 'foo.js'
  82 import * as bar from 'bar.js';
  83 import {a, b} from 'baz.js';
  84 import c from 'qux.js';
  85
  86 /*eslint sort-imports: "error"*/
  87 import {a, b, c} from 'foo.js'
  88 ```
  89
  90 Examples of **incorrect** code for this rule when using default options:
  91
  92 ```js
  93 /*eslint sort-imports: "error"*/
  94 import b from 'foo.js';
  95 import a from 'bar.js';
  96
  97 /*eslint sort-imports: "error"*/
  98 import a from 'foo.js';
  99 import A from 'bar.js';
 100
 101 /*eslint sort-imports: "error"*/
 102 import {b, c} from 'foo.js';
 103 import {a, b} from 'bar.js';
 104
 105 /*eslint sort-imports: "error"*/
 106 import a from 'foo.js';
 107 import {b, c} from 'bar.js';
 108
 109 /*eslint sort-imports: "error"*/
 110 import a from 'foo.js';
 111 import * as b from 'bar.js';
 112
 113 /*eslint sort-imports: "error"*/
 114 import {b, a, c} from 'foo.js'
 115 ```
 116
 117 ### `ignoreCase`
 118
 119 When `true` the rule ignores the case-sensitivity of the imports local name.
 120
 121 Examples of **incorrect** code for this rule with the `{ "ignoreCase": true }` option:
 122
 123 ```js
 124 /*eslint sort-imports: ["error", { "ignoreCase": true }]*/
 125
 126 import B from 'foo.js';
 127 import a from 'bar.js';
 128 ```
 129
 130 Examples of **correct** code for this rule with the `{ "ignoreCase": true }` option:
 131
 132 ```js
 133 /*eslint sort-imports: ["error", { "ignoreCase": true }]*/
 134
 135 import a from 'foo.js';
 136 import B from 'bar.js';
 137 import c from 'baz.js';
 138 ```
 139
 140 Default is `false`.
 141
 142 ### `ignoreDeclarationSort`
 143
 144 Ignores the sorting of import declaration statements.
 145
 146 Examples of **incorrect** code for this rule with the default `{ "ignoreDeclarationSort": false }` option:
 147
 148 ```js
 149 /*eslint sort-imports: ["error", { "ignoreDeclarationSort": false }]*/
 150 import b from 'foo.js'
 151 import a from 'bar.js'
 152 ```
 153
 154 Examples of **correct** code for this rule with the `{ "ignoreDeclarationSort": true }` option:
 155
 156 ```js
 157 /*eslint sort-imports: ["error", { "ignoreDeclarationSort": true }]*/
 158 import a from 'foo.js'
 159 import b from 'bar.js'
 160 ```
 161
 162 ```js
 163 /*eslint sort-imports: ["error", { "ignoreDeclarationSort": true }]*/
 164 import b from 'foo.js'
 165 import a from 'bar.js'
 166 ```
 167
 168 Default is `false`.
 169
 170 ### `ignoreMemberSort`
 171
 172 Ignores the member sorting within a `multiple` member import declaration.
 173
 174 Examples of **incorrect** code for this rule with the default `{ "ignoreMemberSort": false }` option:
 175
 176 ```js
 177 /*eslint sort-imports: ["error", { "ignoreMemberSort": false }]*/
 178 import {b, a, c} from 'foo.js'
 179 ```
 180
 181 Examples of **correct** code for this rule with the `{ "ignoreMemberSort": true }` option:
 182
 183 ```js
 184 /*eslint sort-imports: ["error", { "ignoreMemberSort": true }]*/
 185 import {b, a, c} from 'foo.js'
 186 ```
 187
 188 Default is `false`.
 189
 190 ### `memberSyntaxSortOrder`
 191
 192 There are four different styles and the default member syntax sort order is:
 193
 194 * `none` - import module without exported bindings.
 195 * `all` - import all members provided by exported bindings.
 196 * `multiple` - import multiple members.
 197 * `single` - import single member.
 198
 199 All four options must be specified in the array, but you can customize their order.
 200
 201 Examples of **incorrect** code for this rule with the default `{ "memberSyntaxSortOrder": ["none", "all", "multiple", "single"] }` option:
 202
 203 ```js
 204 /*eslint sort-imports: "error"*/
 205 import a from 'foo.js';
 206 import * as b from 'bar.js';
 207 ```
 208
 209 Examples of **correct** code for this rule with the `{ "memberSyntaxSortOrder": ['single', 'all', 'multiple', 'none'] }` option:
 210
 211 ```js
 212 /*eslint sort-imports: ["error", { "memberSyntaxSortOrder": ['single', 'all', 'multiple', 'none'] }]*/
 213
 214 import a from 'foo.js';
 215 import * as b from 'bar.js';
 216 ```
 217
 218 Examples of **correct** code for this rule with the `{ "memberSyntaxSortOrder": ['all', 'single', 'multiple', 'none'] }` option:
 219
 220 ```js
 221 /*eslint sort-imports: ["error", { "memberSyntaxSortOrder": ['all', 'single', 'multiple', 'none'] }]*/
 222
 223 import * as foo from 'foo.js';
 224 import z from 'zoo.js';
 225 import {a, b} from 'foo.js';
 226 ```
 227
 228 Default is `["none", "all", "multiple", "single"]`.
 229
 230 ### `allowSeparatedGroups`
 231
 232 When `true` the rule checks the sorting of import declaration statements only for those that appear on consecutive lines.
 233
 234 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.
 235
 236 Examples of **incorrect** code for this rule with the `{ "allowSeparatedGroups": true }` option:
 237
 238 ```js
 239 /*eslint sort-imports: ["error", { "allowSeparatedGroups": true }]*/
 240
 241 import b from 'foo.js';
 242 import c from 'bar.js';
 243 import a from 'baz.js';
 244 ```
 245
 246 Examples of **correct** code for this rule with the `{ "allowSeparatedGroups": true }` option:
 247
 248 ```js
 249 /*eslint sort-imports: ["error", { "allowSeparatedGroups": true }]*/
 250
 251 import b from 'foo.js';
 252 import c from 'bar.js';
 253
 254 import a from 'baz.js';
 255 ```
 256
 257 ```js
 258 /*eslint sort-imports: ["error", { "allowSeparatedGroups": true }]*/
 259
 260 import b from 'foo.js';
 261 import c from 'bar.js';
 262 // comment
 263 import a from 'baz.js';
 264 ```
 265
 266 ```js
 267 /*eslint sort-imports: ["error", { "allowSeparatedGroups": true }]*/
 268
 269 import b from 'foo.js';
 270 import c from 'bar.js';
 271 quux();
 272 import a from 'baz.js';
 273 ```
 274
 275 Default is `false`.
 276
 277 ## When Not To Use It
 278
 279 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.
 280
 281 ## Related Rules
 282
 283 * [sort-keys](sort-keys.md)
 284 * [sort-vars](sort-vars.md)