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
  26 ## Rule Details
  27
  28 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.
  29
  30 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.
  31
  32 ## Options
  33
  34 This rule accepts an object with its properties as
  35
  36 * `ignoreCase` (default: `false`)
  37 * `ignoreDeclarationSort` (default: `false`)
  38 * `ignoreMemberSort` (default: `false`)
  39 * `memberSyntaxSortOrder` (default: `["none", "all", "multiple", "single"]`); all 4 items must be present in the array, but you can change the order:
  40     * `none` = import module without exported bindings.
  41     * `all` = import all members provided by exported bindings.
  42     * `multiple` = import multiple members.
  43     * `single` = import single member.
  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     }]
  55 }
  56 ```
  57
  58 ## Examples
  59
  60 ### Default settings
  61
  62 Examples of **correct** code for this rule when using default options:
  63
  64 ```js
  65 /*eslint sort-imports: "error"*/
  66 import 'module-without-export.js';
  67 import * as bar from 'bar.js';
  68 import * as foo from 'foo.js';
  69 import {alpha, beta} from 'alpha.js';
  70 import {delta, gamma} from 'delta.js';
  71 import a from 'baz.js';
  72 import b from 'qux.js';
  73
  74 /*eslint sort-imports: "error"*/
  75 import a from 'foo.js';
  76 import b from 'bar.js';
  77 import c from 'baz.js';
  78
  79 /*eslint sort-imports: "error"*/
  80 import 'foo.js'
  81 import * as bar from 'bar.js';
  82 import {a, b} from 'baz.js';
  83 import c from 'qux.js';
  84
  85 /*eslint sort-imports: "error"*/
  86 import {a, b, c} from 'foo.js'
  87 ```
  88
  89 Examples of **incorrect** code for this rule when using default options:
  90
  91 ```js
  92 /*eslint sort-imports: "error"*/
  93 import b from 'foo.js';
  94 import a from 'bar.js';
  95
  96 /*eslint sort-imports: "error"*/
  97 import a from 'foo.js';
  98 import A from 'bar.js';
  99
 100 /*eslint sort-imports: "error"*/
 101 import {b, c} from 'foo.js';
 102 import {a, b} from 'bar.js';
 103
 104 /*eslint sort-imports: "error"*/
 105 import a from 'foo.js';
 106 import {b, c} from 'bar.js';
 107
 108 /*eslint sort-imports: "error"*/
 109 import a from 'foo.js';
 110 import * as b from 'bar.js';
 111
 112 /*eslint sort-imports: "error"*/
 113 import {b, a, c} from 'foo.js'
 114 ```
 115
 116 ### `ignoreCase`
 117
 118 When `true` the rule ignores the case-sensitivity of the imports local name.
 119
 120 Examples of **incorrect** code for this rule with the `{ "ignoreCase": true }` option:
 121
 122 ```js
 123 /*eslint sort-imports: ["error", { "ignoreCase": true }]*/
 124
 125 import B from 'foo.js';
 126 import a from 'bar.js';
 127 ```
 128
 129 Examples of **correct** code for this rule with the `{ "ignoreCase": true }` option:
 130
 131 ```js
 132 /*eslint sort-imports: ["error", { "ignoreCase": true }]*/
 133
 134 import a from 'foo.js';
 135 import B from 'bar.js';
 136 import c from 'baz.js';
 137 ```
 138
 139 Default is `false`.
 140
 141 ### `ignoreDeclarationSort`
 142
 143 Ignores the sorting of import declaration statements.
 144
 145 Examples of **incorrect** code for this rule with the default `{ "ignoreDeclarationSort": false }` option:
 146
 147 ```js
 148 /*eslint sort-imports: ["error", { "ignoreDeclarationSort": false }]*/
 149 import b from 'foo.js'
 150 import a from 'bar.js'
 151 ```
 152
 153 Examples of **correct** code for this rule with the `{ "ignoreDeclarationSort": true }` option:
 154
 155 ```js
 156 /*eslint sort-imports: ["error", { "ignoreDeclarationSort": true }]*/
 157 import a from 'foo.js'
 158 import b from 'bar.js'
 159 ```
 160
 161 ```js
 162 /*eslint sort-imports: ["error", { "ignoreDeclarationSort": true }]*/
 163 import b from 'foo.js'
 164 import a from 'bar.js'
 165 ```
 166
 167 Default is `false`.
 168
 169 ### `ignoreMemberSort`
 170
 171 Ignores the member sorting within a `multiple` member import declaration.
 172
 173 Examples of **incorrect** code for this rule with the default `{ "ignoreMemberSort": false }` option:
 174
 175 ```js
 176 /*eslint sort-imports: ["error", { "ignoreMemberSort": false }]*/
 177 import {b, a, c} from 'foo.js'
 178 ```
 179
 180 Examples of **correct** code for this rule with the `{ "ignoreMemberSort": true }` option:
 181
 182 ```js
 183 /*eslint sort-imports: ["error", { "ignoreMemberSort": true }]*/
 184 import {b, a, c} from 'foo.js'
 185 ```
 186
 187 Default is `false`.
 188
 189 ### `memberSyntaxSortOrder`
 190
 191 There are four different styles and the default member syntax sort order is:
 192
 193 * `none` - import module without exported bindings.
 194 * `all` - import all members provided by exported bindings.
 195 * `multiple` - import multiple members.
 196 * `single` - import single member.
 197
 198 All four options must be specified in the array, but you can customize their order.
 199
 200 Examples of **incorrect** code for this rule with the default `{ "memberSyntaxSortOrder": ["none", "all", "multiple", "single"] }` option:
 201
 202 ```js
 203 /*eslint sort-imports: "error"*/
 204 import a from 'foo.js';
 205 import * as b from 'bar.js';
 206 ```
 207
 208 Examples of **correct** code for this rule with the `{ "memberSyntaxSortOrder": ['single', 'all', 'multiple', 'none'] }` option:
 209
 210 ```js
 211 /*eslint sort-imports: ["error", { "memberSyntaxSortOrder": ['single', 'all', 'multiple', 'none'] }]*/
 212
 213 import a from 'foo.js';
 214 import * as b from 'bar.js';
 215 ```
 216
 217 Examples of **correct** code for this rule with the `{ "memberSyntaxSortOrder": ['all', 'single', 'multiple', 'none'] }` option:
 218
 219 ```js
 220 /*eslint sort-imports: ["error", { "memberSyntaxSortOrder": ['all', 'single', 'multiple', 'none'] }]*/
 221
 222 import * as foo from 'foo.js';
 223 import z from 'zoo.js';
 224 import {a, b} from 'foo.js';
 225 ```
 226
 227 Default is `["none", "all", "multiple", "single"]`.
 228
 229 ## When Not To Use It
 230
 231 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.
 232
 233 ## Related Rules
 234
 235 * [sort-keys](sort-keys.md)
 236 * [sort-vars](sort-vars.md)