0
# Prettier Plugin Sort Imports
1

2
@ianvs/prettier-plugin-sort-imports is a Prettier plugin that automatically sorts import declarations according to customizable Regular Expression patterns while preserving side-effect import order. It extends the functionality of @trivago/prettier-plugin-sort-imports with enhanced features including the ability to combine imports from the same source, merge type and value imports for TypeScript 4.5.0+, group type imports with `<TYPES>` keyword, prioritize Node.js builtin modules with `<BUILTIN_MODULES>` keyword, handle comments around imports correctly, and provide flexible import order separation.
3

4
## Package Information
5

6
- **Package Name**: @ianvs/prettier-plugin-sort-imports
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @ianvs/prettier-plugin-sort-imports`
10

11
## Core Imports
12

13
This is a Prettier plugin, so it doesn't export functions for direct import. Instead, it integrates with Prettier's plugin system automatically when installed and configured.
14

15
## Basic Usage
16

17
### Installation and Configuration
18

19
Add to your Prettier configuration:
20

21
```json
22
{
23
  "plugins": ["@ianvs/prettier-plugin-sort-imports"],
24
  "importOrder": [
25
    "^@core/(.*)$",
26
    "^@server/(.*)$", 
27
    "^@ui/(.*)$",
28
    "^[./]"
29
  ]
30
}
31
```
32

33
### Example Input/Output
34

35
**Input:**
36
```typescript
37
import { logger } from '@core/logger';
38
import React, { FC, useEffect } from 'react';
39
import { reduce, debounce } from 'lodash';
40
import { Alert } from '@ui/Alert';
41
import { Message } from '../Message';
42
import { createServer } from '@server/node';
43
```
44

45
**Output:**
46
```typescript
47
import { debounce, reduce } from 'lodash';
48
import React, { FC, useEffect } from 'react';
49

50
import { createServer } from '@server/node';
51

52
import { logger } from '@core/logger';
53

54
import { Alert } from '@ui/Alert';
55

56
import { Message } from '../Message';
57
```
58

59
## Capabilities
60

61
### Plugin Configuration Options
62

63
The plugin accepts these configuration options through Prettier's options system:
64

65
```typescript { .api }
66
interface PluginConfig {
67
  /**
68
   * A collection of Regular expressions in string format.
69
   * Default: ["<BUILTIN_MODULES>", "<THIRD_PARTY_MODULES>", "^[.]"]
70
   */
71
  importOrder?: string[];
72

73
  /**
74
   * Version of TypeScript in use in the project. Determines some output syntax.
75
   * Default: "1.0.0"
76
   */
77
  importOrderTypeScriptVersion?: string;
78

79
  /**
80
   * Should capitalization be considered when sorting imports?
81
   * Default: false
82
   */
83
  importOrderCaseSensitive?: boolean;
84

85
  /**
86
   * A collection of plugins for babel parser. The plugin uses prettier itself 
87
   * to figure out the parser but if that fails, you can use this field.
88
   * Default: ["typescript", "jsx"]
89
   */
90
  importOrderParserPlugins?: ImportOrderParserPlugin[];
91

92
  /**
93
   * Array of globs for side-effect-only imports that are considered safe to sort.
94
   * Default: []
95
   */
96
  importOrderSafeSideEffects?: string[];
97
}
98

99
type ImportOrderParserPlugin = 
100
  | Extract<ParserPlugin, string>
101
  | `[${string},${string}]`;
102
```
103

104
### Import Order Patterns
105

106
The `importOrder` option accepts an array of regex patterns with special keywords:
107

108
```typescript { .api }
109
/**
110
 * Special keywords for import ordering:
111
 */
112
type SpecialKeywords = 
113
  | "<BUILTIN_MODULES>"     // Node.js builtin modules (fs, path, etc.)
114
  | "<THIRD_PARTY_MODULES>" // Third-party packages from node_modules
115
  | "<TYPES>";              // TypeScript type-only imports
116

117
/**
118
 * Default import order configuration
119
 */
120
const DEFAULT_IMPORT_ORDER: string[] = [
121
  "<BUILTIN_MODULES>",
122
  "<THIRD_PARTY_MODULES>", 
123
  "^[.]" // Relative imports
124
];
125
```
126

127
### Parser Configuration
128

129
The plugin extends Prettier's built-in parsers with import sorting preprocessing:
130

131
```typescript { .api }
132
/**
133
 * Available parsers with sorting support
134
 */
135
interface ExtendedParsers {
136
  babel: Parser;         // JavaScript with Babel
137
  "babel-ts": Parser;    // TypeScript with Babel
138
  typescript: Parser;    // TypeScript
139
  flow: Parser;          // Flow
140
  vue: Parser;           // Vue SFC
141
  "ember-template-tag": Parser; // Ember (requires prettier-plugin-ember-template-tag)
142
  oxc: Parser;           // Oxc parser (requires @prettier/plugin-oxc)
143
  "oxc-ts": Parser;      // Oxc TypeScript (requires @prettier/plugin-oxc)
144
}
145

146
/**
147
 * Available printers
148
 */
149
interface ExtendedPrinters {
150
  "estree-oxc": Printer; // Oxc ESTree printer (requires @prettier/plugin-oxc)
151
}
152
```
153

154
### Plugin Integration
155

156
The plugin automatically integrates with Prettier when installed. It exports the standard Prettier plugin interface:
157

158
```typescript { .api }
159
/**
160
 * Main plugin exports for Prettier integration
161
 */
162
interface PrettierPlugin {
163
  /** Plugin configuration options schema */
164
  options: Record<keyof PluginConfig, SupportOption>;
165
  
166
  /** Extended parsers with import sorting preprocessing */
167
  parsers: ExtendedParsers;
168
  
169
  /** Extended printers for specific syntax support */
170
  printers: ExtendedPrinters;
171
}
172
```
173

174
## Types
175

176
### Core Configuration Types
177

178
```typescript { .api }
179
/**
180
 * Combined configuration type for Prettier integration
181
 */
182
type PrettierConfig = PluginConfig & Config;
183

184
/**
185
 * Parser plugin specification for Babel
186
 */
187
type ImportOrderParserPlugin =
188
  | Extract<ParserPlugin, string>
189
  | `[${string},${string}]`;
190
```
191

192
### Internal Processing Types
193

194
```typescript { .api }
195
/**
196
 * Prettier options extended with plugin configuration
197
 */
198
interface PrettierOptions extends Required<PluginConfig>, RequiredOptions {}
199

200
/**
201
 * Subset of options that need normalization
202
 */
203
type NormalizableOptions = Pick<
204
  PrettierOptions,
205
  | 'importOrder'
206
  | 'importOrderParserPlugins'
207
  | 'importOrderTypeScriptVersion'
208
  | 'importOrderCaseSensitive'
209
  | 'importOrderSafeSideEffects'
210
> & Pick<Partial<PrettierOptions>, 'filepath'>;
211

212
/**
213
 * Import declarations grouped by type
214
 */
215
interface ImportChunk {
216
  nodes: ImportDeclaration[];
217
  type: ChunkType;
218
}
219

220
type ChunkType = 'other' | 'unsortable';
221

222
/**
223
 * Mapping of import groups to their declarations
224
 */
225
type ImportGroups = Record<string, ImportDeclaration[]>;
226
```
227

228
## Module Declaration
229

230
The plugin extends Prettier's Options interface with its configuration:
231

232
```typescript { .api }
233
declare module 'prettier' {
234
  interface Options extends PluginConfig {}
235
}
236
```
237

238
## Configuration Examples
239

240
### Basic Configuration
241

242
```json
243
{
244
  "plugins": ["@ianvs/prettier-plugin-sort-imports"],
245
  "importOrder": [
246
    "^@core/(.*)$",
247
    "^@server/(.*)$",
248
    "^@ui/(.*)$", 
249
    "^[./]"
250
  ]
251
}
252
```
253

254
### Advanced Configuration with Type Separation
255

256
```json
257
{
258
  "plugins": ["@ianvs/prettier-plugin-sort-imports"],
259
  "importOrder": [
260
    "<TYPES>",
261
    "<TYPES>^[./]",
262
    "<BUILTIN_MODULES>",
263
    "<THIRD_PARTY_MODULES>",
264
    "^@core/(.*)$",
265
    "^[./]"
266
  ],
267
  "importOrderCaseSensitive": true,
268
  "importOrderTypeScriptVersion": "4.5.0",
269
  "importOrderParserPlugins": ["typescript", "jsx", "decorators-legacy"]
270
}
271
```
272

273
### Safe Side Effects Configuration
274

275
```json
276
{
277
  "plugins": ["@ianvs/prettier-plugin-sort-imports"],
278
  "importOrder": [
279
    "<BUILTIN_MODULES>",
280
    "<THIRD_PARTY_MODULES>",
281
    "^[./]"
282
  ],
283
  "importOrderSafeSideEffects": [
284
    "^server-only$",
285
    "^reflect-metadata$"
286
  ]
287
}
288
```
289

290
## Preventing Import Sorting
291

292
Use `// prettier-ignore` to prevent specific imports from being sorted:
293

294
```typescript
295
// prettier-ignore
296
import { sideEffectModule } from "./side-effect-module";
297

298
import { regularImport } from "./regular-module";
299
```