import-sort-style-module-and-prefix
Version:
An [import sort](https://github.com/renke/import-sort) style based on [`import-sort-style-module`](https://github.com/renke/import-sort/tree/master/packages/import-sort-style-module) that support extra groupings by path prefix.
345 lines (266 loc) • 10.3 kB
Markdown
# import-sort-style-module-and-prefix
An [import sort](https://github.com/renke/import-sort) style based on [`import-sort-style-module`](https://github.com/renke/import-sort/tree/master/packages/import-sort-style-module) that support extra groupings by path prefix.
# Install
Install this package through `npm`:
```bash
npm install --save-dev import-sort-style-module-and-prefix
```
or `yarn`:
```bash
yarn add -D import-sort-style-module-and-prefix
```
In your `package.json` or `.importsortrc`, specify `module-and-prefix` as the `style` for file groups which you want to use this style.
For example, in `package.json`:
```json
"importSort": {
".js, .jsx, .ts, .tsx": {
"style": "module-and-prefix"
}
}
```
# Configuration
This module works exactly the same as `import-sort-style-module` if no extra configuration is done.
The configuration either lies under the key `importSortPrefix` in your `package.json`, in a file named `.importSortPrefixrc`. Thanks to [cosmiconfig](https://github.com/davidtheclark/cosmiconfig), `.importSortPrefixrc` can be of JSON or YAML format. Format can be explicited specified by the file extension. Please refer to [cosmiconfig](https://github.com/davidtheclark/cosmiconfig#cosmiconfig) for further information.
## Sample configurations
1. Groups all imports with path matching the prefix `src/`, and places them above the imports with relative path.
```json
{ "groupings": ["src/"] }
```
2. Groups all imports with path matching the prefix `src/` or `components/` together, and those matching the prefix `lib/` in another group.
```json
{ "groupings": [["src/", "components/"], "lib/"] }
```
## Options
There are two options available:
* [`position`](#position) - Accepted values: `beforeAbsolute`, `beforeBuiltins`, `beforeRelative`, `afterRelative`. **Default**: `beforeRelative`
* [`groupings`](#groupings) - Array of \[string or array of string] `(string | string[])[]`. **Default**: `[]`
### `position`
If not specified, the default value `beforeRelative` is used.
To illustrate each value, let's consider the following examples adapted from [import-sort-style-module](https://github.com/renke/import-sort/tree/master/packages/import-sort-style-module), and assume we have a custom group for modules matching the path prefix `src/`.
<details><summary><code>beforeAbsolute</code></summary>
```js
/*******************************************
*
* Absolute module without assigned imports
*
*******************************************/
import "src";
import "src/some_module";
import "src/helpers/some_helper";
// Absolute modules with side effects (not sorted because order may matter)
import "a";
import "c";
import "b";
// Relative modules with side effects (not sorted because order may matter)
import "./a";
import "./c";
import "./b";
// Modules from the Node.js "standard" library sorted by name
import {readFile, writeFile} from "fs";
import * as path from "path";
/*******************************************
*
* Ordinary absolute module imports
*
*******************************************/
import indexModule from "src";
import {namedExport} from "src/some_module";
import helperFunc from "src/helpers/some_helper";
// Third-party modules sorted by name
import aa from "aa";
import bb from "bb";
import cc from "cc";
// First-party modules sorted by "relative depth" and then by name
import aaa from "../../aaa";
import bbb from "../../bbb";
import aaaa from "../aaaa";
import bbbb from "../bbbb";
import aaaaa from "./aaaaa";
import bbbbb from "./bbbbb";
```
</details>
<details><summary><code>beforeBuiltins</code></summary>
```js
/*******************************************
*
* Absolute module without assigned imports
*
******************************************/
import "src";
import "src/some_module";
import "src/helpers/some_helper";
// Absolute modules with side effects (not sorted because order may matter)
import "a";
import "c";
import "b";
// Relative modules with side effects (not sorted because order may matter)
import "./a";
import "./c";
import "./b";
/*******************************************
*
* Ordinary absolute module imports
*
******************************************/
import indexModule from "src";
import {namedExport} from "src/some_module";
import helperFunc from "src/helpers/some_helper";
// Modules from the Node.js "standard" library sorted by name
import {readFile, writeFile} from "fs";
import * as path from "path";
// Third-party modules sorted by name
import aa from "aa";
import bb from "bb";
import cc from "cc";
// First-party modules sorted by "relative depth" and then by name
import aaa from "../../aaa";
import bbb from "../../bbb";
import aaaa from "../aaaa";
import bbbb from "../bbbb";
import aaaaa from "./aaaaa";
import bbbbb from "./bbbbb";
```
</details>
<details><summary><code>beforeRelative</code> <em>(default)</em></summary>
```js
// Absolute modules with side effects (not sorted because order may matter)
import "a";
import "c";
import "b";
/*******************************************
*
* Absolute module without assigned imports
*
******************************************/
import "src";
import "src/some_module";
import "src/helpers/some_helper";
// Relative modules with side effects (not sorted because order may matter)
import "./a";
import "./c";
import "./b";
// Modules from the Node.js "standard" library sorted by name
import {readFile, writeFile} from "fs";
import * as path from "path";
// Third-party modules sorted by name
import aa from "aa";
import bb from "bb";
import cc from "cc";
/*******************************************
*
* Ordinary absolute module imports
*
******************************************/
import indexModule from "src";
import {namedExport} from "src/some_module";
import helperFunc from "src/helpers/some_helper";
// First-party modules sorted by "relative depth" and then by name
import aaa from "../../aaa";
import bbb from "../../bbb";
import aaaa from "../aaaa";
import bbbb from "../bbbb";
import aaaaa from "./aaaaa";
import bbbbb from "./bbbbb";
```
</details>
<details><summary><code>afterRelative</code></summary>
```js
// Absolute modules with side effects (not sorted because order may matter)
import "a";
import "c";
import "b";
// Relative modules with side effects (not sorted because order may matter)
import "./a";
import "./c";
import "./b";
/*******************************************
*
* Absolute module without assigned imports
*
******************************************/
import "src";
import "src/some_module";
import "src/helpers/some_helper";
// Modules from the Node.js "standard" library sorted by name
import {readFile, writeFile} from "fs";
import * as path from "path";
// Third-party modules sorted by name
import aa from "aa";
import bb from "bb";
import cc from "cc";
// First-party modules sorted by "relative depth" and then by name
import aaa from "../../aaa";
import bbb from "../../bbb";
import aaaa from "../aaaa";
import bbbb from "../bbbb";
import aaaaa from "./aaaaa";
import bbbbb from "./bbbbb";
/*******************************************
*
* Ordinary absolute module imports
*
******************************************/
import indexModule from "src";
import {namedExport} from "src/some_module";
import helperFunc from "src/helpers/some_helper";
```
</details>
### `groupings`
This option defines custom groupings and accepts an array. Each array item can either be a path prefix, or an array of path prefixes.
If not specified, the default value `[]` is assumed. In such case, this style works exactly the same as [import-sort-style-module](https://github.com/renke/import-sort/tree/master/packages/import-sort-style-module).
Each item in the `groupings` array corrisponds to one group, i.e. a chunk of import statements that does not contain any empty line.
To group multiple path prefixes into one group, place them in an array. Refer to [Example 2](#2-groups-of-path-prefixes) for an example.
The custom groups will appear in the same order as specified in the option.
#### Examples
##### 1. Simple path prefix groups:
Options:
```json
{ "groupings": ["src/", "@helpers/", "@components/", "lib/"] }
```
Imports matching each of the specified path prefix will be grouped into their corrisponding group.
```js
// Third-party modules sorted by name
import aa from "aa";
import bb from "bb";
import cc from "cc";
/** Custom import groups */
import indexModule from "src";
import {namedExport} from "src/some_module";
import helperFunc from "@helpers/some_helper";
import ExternalLib, {libHelperFunc} from "lib/external_lib";
// First-party modules sorted by "relative depth" and then by name
import aaa from "../../aaa";
import bbb from "../../bbb";
import aaaa from "../aaaa";
import bbbb from "../bbbb";
import aaaaa from "./aaaaa";
import bbbbb from "./bbbbb";
```
Take note that the `src/` group appears before the `@helpers/` group, in the same order as the `groupings` option, regardless of alphabetical order. `lib/` group comes after `@helpers/` group, the two groups separated by exactly one empty line, unaffected by the empty `/` group.
<a id="example-2"></a>
##### 2. Groups of path prefixes
Options:
```json
{ "groupings": [["src/", "@helpers/"], "@components/", "lib/"] }
```
Imports matching each of the specified path prefix **group** will be grouped into their corrisponding group. In other words, imports matching the path prefixes `src/` or `@helpers/` are grouped together, with the ones matching `src/` come before those matching `@helpers/`; imports matching `lib/` are in their own group.
```js
// Third-party modules sorted by name
import aa from "aa";
import bb from "bb";
import cc from "cc";
/** Custom import groups */
import indexModule from "src";
import {namedExport} from "src/some_module";
import helperFunc from "@helpers/some_helper";
import ExternalLib, {libHelperFunc} from "lib/external_lib";
// First-party modules sorted by "relative depth" and then by name
import aaa from "../../aaa";
import bbb from "../../bbb";
import aaaa from "../aaaa";
import bbbb from "../bbbb";
import aaaaa from "./aaaaa";
import bbbbb from "./bbbbb";
```
# License
Released under [the MIT License](https://opensource.org/licenses/MIT). :copyright: 2020 Ron Lau.