You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: docs/rules/order.md
+277-9
Original file line number
Diff line number
Diff line change
@@ -108,6 +108,7 @@ This rule supports the following options (none of which are required):
108
108
-[`warnOnUnassignedImports`][5]
109
109
-[`sortTypesGroup`][7]
110
110
-[`newlines-between-types`][27]
111
+
-[`consolidateIslands`][25]
111
112
112
113
---
113
114
@@ -184,7 +185,7 @@ Sometimes [the predefined groups][18] are not fine-grained enough, especially wh
184
185
`pathGroups` defines one or more [`PathGroup`][13]s relative to a predefined group.
185
186
Imports are associated with a [`PathGroup`][13] based on path matching against the import specifier (using [minimatch][14]).
186
187
187
-
> \[!IMPORTANT]
188
+
> [!IMPORTANT]
188
189
>
189
190
> Note that, by default, imports grouped as `"builtin"`, `"external"`, or `"object"` will not be considered for further `pathGroups` matching unless they are removed from [`pathGroupsExcludedImportTypes`][9].
> This setting is only meaningful when [`sortTypesGroup`][7] is enabled.
604
605
@@ -656,9 +657,9 @@ The same example will pass.
656
657
657
658
Note the new line after `import type E from './';` but before `import a from "fs";`. This new line separates the type-only imports from the normal imports. Its existence is governed by [`newlines-between-types`][27] and _not `newlines-between`_.
658
659
659
-
> \[!IMPORTANT]
660
+
> [!IMPORTANT]
660
661
>
661
-
> In certain situations, `consolidateIslands: true` will take precedence over `newlines-between-types: "never"`, if used, when it comes to the new line separating type-only imports from normal imports.
662
+
> In certain situations, [`consolidateIslands: true`][25] will take precedence over `newlines-between-types: "never"`, if used, when it comes to the new line separating type-only imports from normal imports.
662
663
663
664
The next example will pass even though there's a new line preceding the normal import and [`newlines-between`][20] is set to `"never"`:
664
665
@@ -722,6 +723,272 @@ import d from "./bar.js";
722
723
importefrom"./";
723
724
```
724
725
726
+
### `consolidateIslands`
727
+
728
+
Valid values: `"inside-groups" | "never"`\
729
+
Default: `"never"`
730
+
731
+
> [!NOTE]
732
+
>
733
+
> This setting is only meaningful when [`newlines-between`][20] and/or [`newlines-between-types`][27] is set to `"always-and-inside-groups"`.
734
+
735
+
When set to `"inside-groups"`, this ensures imports spanning multiple lines are separated from other imports with a new line while single-line imports are grouped together (and the space between them consolidated) if they belong to the same [group][18] or [`pathGroups`][8].
736
+
737
+
> [!IMPORTANT]
738
+
>
739
+
> When all of the following are true:
740
+
>
741
+
> -[`sortTypesGroup`][7] is set to `true`
742
+
> -`consolidateIslands` is set to `"inside-groups"`
743
+
> -[`newlines-between`][20] is set to `"always-and-inside-groups"` when [`newlines-between-types`][27] is set to `"never"` (or vice-versa)
744
+
>
745
+
> Then [`newlines-between`][20]/[`newlines-between-types`][27] will yield to
746
+
> `consolidateIslands` and allow new lines to separate multi-line imports
747
+
> regardless of the `"never"` setting.
748
+
>
749
+
> This configuration is useful, for instance, to keep single-line type-only
750
+
> imports stacked tightly together at the bottom of your import block to
751
+
> preserve space while still logically organizing normal imports for quick and
752
+
> pleasant reference.
753
+
754
+
#### Example
755
+
756
+
Given the following settings:
757
+
758
+
```jsonc
759
+
{
760
+
"import/order": ["error", {
761
+
"newlines-between":"always-and-inside-groups",
762
+
"consolidateIslands":"inside-groups"
763
+
}]
764
+
}
765
+
```
766
+
767
+
This will fail the rule check:
768
+
769
+
```ts
770
+
var fs =require('fs');
771
+
var path =require('path');
772
+
var { util1, util2, util3 } =require('util');
773
+
var async =require('async');
774
+
var relParent1 =require('../foo');
775
+
var {
776
+
relParent21,
777
+
relParent22,
778
+
relParent23,
779
+
relParent24,
780
+
} =require('../');
781
+
var relParent3 =require('../bar');
782
+
var { sibling1,
783
+
sibling2, sibling3 } =require('./foo');
784
+
var sibling2 =require('./bar');
785
+
var sibling3 =require('./foobar');
786
+
```
787
+
788
+
While this will succeed (and is what `--fix` would yield):
789
+
790
+
```ts
791
+
var fs =require('fs');
792
+
var path =require('path');
793
+
var { util1, util2, util3 } =require('util');
794
+
795
+
var async =require('async');
796
+
797
+
var relParent1 =require('../foo');
798
+
799
+
var {
800
+
relParent21,
801
+
relParent22,
802
+
relParent23,
803
+
relParent24,
804
+
} =require('../');
805
+
806
+
var relParent3 =require('../bar');
807
+
808
+
var { sibling1,
809
+
sibling2, sibling3 } =require('./foo');
810
+
811
+
var sibling2 =require('./bar');
812
+
var sibling3 =require('./foobar');
813
+
```
814
+
815
+
Note the intragroup "islands" of grouped single-line imports, as well as multi-line imports, are surrounded by new lines. At the same time, note the typical new lines separating different groups are still maintained thanks to [`newlines-between`][20].
816
+
817
+
The same holds true for the next example; when given the following settings:
> **Pay special attention to the value of [`pathGroupsExcludedImportTypes`][9]** in this example's settings.
852
+
> Without it, the successful example below would fail.
853
+
> This is because the imports with specifiers starting with "dirA/", "dirB/", and "dirC/" are all [considered part of the `"external"` group](#how-imports-are-grouped), and imports in that group are excluded from [`pathGroups`][8] matching by default.
854
+
>
855
+
> The fix is to remove `"external"` (and, in this example, the others) from [`pathGroupsExcludedImportTypes`][9].
856
+
857
+
This will fail the rule check:
858
+
859
+
```ts
860
+
importcfrom'Bar';
861
+
importdfrom'bar';
862
+
import {
863
+
aa,
864
+
bb,
865
+
cc,
866
+
dd,
867
+
ee,
868
+
ff,
869
+
gg
870
+
} from'baz';
871
+
import {
872
+
hh,
873
+
ii,
874
+
jj,
875
+
kk,
876
+
ll,
877
+
mm,
878
+
nn
879
+
} from'fizz';
880
+
importafrom'foo';
881
+
importbfrom'dirA/bar';
882
+
importindexfrom'./';
883
+
importtype { AA,
884
+
BB, CC } from'abc';
885
+
importtype { Z } from'fizz';
886
+
importtype {
887
+
A,
888
+
B
889
+
} from'foo';
890
+
importtype { C2 } from'dirB/Bar';
891
+
importtype {
892
+
D2,
893
+
X2,
894
+
Y2
895
+
} from'dirB/bar';
896
+
importtype { E2 } from'dirB/baz';
897
+
importtype { C3 } from'dirC/Bar';
898
+
importtype {
899
+
D3,
900
+
X3,
901
+
Y3
902
+
} from'dirC/bar';
903
+
importtype { E3 } from'dirC/baz';
904
+
importtype { F3 } from'dirC/caz';
905
+
importtype { C1 } from'dirA/Bar';
906
+
importtype {
907
+
D1,
908
+
X1,
909
+
Y1
910
+
} from'dirA/bar';
911
+
importtype { E1 } from'dirA/baz';
912
+
importtype { F } from'./index.js';
913
+
importtype { G } from'./aaa.js';
914
+
importtype { H } from'./bbb';
915
+
```
916
+
917
+
While this will succeed (and is what `--fix` would yield):
0 commit comments