Skip to content

Commit

Permalink
[Docs] order: improve the documentation for the `pathGroupsExcluded…
Browse files Browse the repository at this point in the history 
…ImportTypes` option
  • Loading branch information
@liby
liby committed Jul 22, 2021
1 parent 1012eb9 commit 0eb0136
Showing 1 changed file with 117 additions and 87 deletions.
204 changes: 117 additions & 87 deletions docs/rules/order.md
View file
Expand Up @@ -33,47 +33,45 @@ Unassigned imports are ignored, as the order they are imported in may be importa

Statements using the ES6 `import` syntax must appear before any `require()` statements.


## Fail

```js
import _ from 'lodash';
import path from 'path'; // `path` import should occur before import of `lodash`
import _ from "lodash";
import path from "path"; // `path` import should occur before import of `lodash`

// -----

var _ = require('lodash');
var path = require('path'); // `path` import should occur before import of `lodash`
var _ = require("lodash");
var path = require("path"); // `path` import should occur before import of `lodash`

// -----

var path = require('path');
import foo from './foo'; // `import` statements must be before `require` statement
var path = require("path");
import foo from "./foo"; // `import` statements must be before `require` statement
```


## Pass

```js
import path from 'path';
import _ from 'lodash';
import path from "path";
import _ from "lodash";

// -----

var path = require('path');
var _ = require('lodash');
var path = require("path");
var _ = require("lodash");

// -----

// Allowed as ̀`babel-register` is not assigned.
require('babel-register');
var path = require('path');
require("babel-register");
var path = require("path");

// -----

// Allowed as `import` must be before `require`
import foo from './foo';
var path = require('path');
import foo from "./foo";
var path = require("path");
```

## Options
Expand All @@ -85,15 +83,17 @@ This rule supports the following options:
How groups are defined, and the order to respect. `groups` must be an array of `string` or [`string`]. The only allowed `string`s are:
`"builtin"`, `"external"`, `"internal"`, `"unknown"`, `"parent"`, `"sibling"`, `"index"`, `"object"`, `"type"`.
The enforced order is the same as the order of each element in a group. Omitted types are implicitly grouped together as the last element. Example:

```js
[
'builtin', // Built-in types are first
['sibling', 'parent'], // Then sibling and parent types. They can be mingled together
'index', // Then the index file
'object',
"builtin", // Built-in types are first
["sibling", "parent"], // Then sibling and parent types. They can be mingled together
"index", // Then the index file
"object",
// Then the rest: internal and external type
]
];
```

The default value is `["builtin", "external", "parent", "sibling", "index"]`.

You can set the options like this:
Expand All @@ -108,23 +108,26 @@ To be able to group by paths mostly needed with aliases pathGroups can be define

Properties of the objects

| property | required | type | description |
|----------------|:--------:|--------|---------------|
| pattern | x | string | minimatch pattern for the paths to be in this group (will not be used for builtins or externals) |
| patternOptions | | object | options for minimatch, default: { nocomment: true } |
| group | x | string | one of the allowed groups, the pathGroup will be positioned relative to this group |
| property | required | type | description |
| -------------- | :------: | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pattern | x | string | minimatch pattern for the paths to be in this group (will not be used for builtins or externals) |
| patternOptions | | object | options for minimatch, default: { nocomment: true } |
| group | x | string | one of the allowed groups, the pathGroup will be positioned relative to this group |
| position | | string | defines where around the group the pathGroup will be positioned, can be 'after' or 'before', if not provided pathGroup will be positioned like the group |

```json
{
"import/order": ["error", {
"pathGroups": [
{
"pattern": "~/**",
"group": "external"
}
]
}]
"import/order": [
"error",
{
"pathGroups": [
{
"pattern": "~/**",
"group": "external"
}
]
}
]
}
```

Expand All @@ -134,20 +137,47 @@ This defines import types that are not handled by configured pathGroups.
This is mostly needed when you want to handle path groups that look like external imports.

Example:

```json
{
"import/order": [
"error",
{
"pathGroups": [
{
"pattern": "@app/**",
"group": "external",
"position": "after"
}
],
"pathGroupsExcludedImportTypes": ["builtin"]
}
]
}
```

You can also use `patterns`(e.g., `react`, `react-router-dom`, etc).

Example:

```json
{
"import/order": ["error", {
"pathGroups": [
{
"pattern": "@app/**",
"group": "external",
"position": "after"
}
],
"pathGroupsExcludedImportTypes": ["builtin"]
}]
"import/order": [
"error",
{
"pathGroups": [
{
"pattern": "react",
"group": "builtin",
"position": "before"
}
],
"pathGroupsExcludedImportTypes": ["react"]
}
]
}
```

The default value is `["builtin", "external"]`.

### `newlines-between: [ignore|always|always-and-inside-groups|never]`:
Expand All @@ -163,60 +193,60 @@ With the default group setting, the following will be invalid:

```js
/* eslint import/order: ["error", {"newlines-between": "always"}] */
import fs from 'fs';
import path from 'path';
import index from './';
import sibling from './foo';
import fs from "fs";
import path from "path";
import index from "./";
import sibling from "./foo";
```

```js
/* eslint import/order: ["error", {"newlines-between": "always-and-inside-groups"}] */
import fs from 'fs';
import fs from "fs";

import path from 'path';
import index from './';
import sibling from './foo';
import path from "path";
import index from "./";
import sibling from "./foo";
```

```js
/* eslint import/order: ["error", {"newlines-between": "never"}] */
import fs from 'fs';
import path from 'path';
import fs from "fs";
import path from "path";

import index from './';
import index from "./";

import sibling from './foo';
import sibling from "./foo";
```

while those will be valid:

```js
/* eslint import/order: ["error", {"newlines-between": "always"}] */
import fs from 'fs';
import path from 'path';
import fs from "fs";
import path from "path";

import index from './';
import index from "./";

import sibling from './foo';
import sibling from "./foo";
```

```js
/* eslint import/order: ["error", {"newlines-between": "always-and-inside-groups"}] */
import fs from 'fs';
import fs from "fs";

import path from 'path';
import path from "path";

import index from './';
import index from "./";

import sibling from './foo';
import sibling from "./foo";
```

```js
/* eslint import/order: ["error", {"newlines-between": "never"}] */
import fs from 'fs';
import path from 'path';
import index from './';
import sibling from './foo';
import fs from "fs";
import path from "path";
import index from "./";
import sibling from "./foo";
```

### `alphabetize: {order: asc|desc|ignore, caseInsensitive: true|false}`:
Expand All @@ -227,6 +257,7 @@ Sort the order within each group in alphabetical manner based on **import path**
- `caseInsensitive`: use `true` to ignore case, and `false` to consider case (default: `false`).

Example setting:

```js
alphabetize: {
order: 'asc', /* sort in ascending order. Options: ['ignore', 'asc', 'desc'] */
Expand All @@ -238,29 +269,29 @@ This will fail the rule check:

```js
/* eslint import/order: ["error", {"alphabetize": {"order": "asc", "caseInsensitive": true}}] */
import React, { PureComponent } from 'react';
import aTypes from 'prop-types';
import { compose, apply } from 'xcompose';
import * as classnames from 'classnames';
import blist from 'BList';
import React, { PureComponent } from "react";
import aTypes from "prop-types";
import { compose, apply } from "xcompose";
import * as classnames from "classnames";
import blist from "BList";
```

While this will pass:

```js
/* eslint import/order: ["error", {"alphabetize": {"order": "asc", "caseInsensitive": true}}] */
import blist from 'BList';
import * as classnames from 'classnames';
import aTypes from 'prop-types';
import React, { PureComponent } from 'react';
import { compose, apply } from 'xcompose';
import blist from "BList";
import * as classnames from "classnames";
import aTypes from "prop-types";
import React, { PureComponent } from "react";
import { compose, apply } from "xcompose";
```

### `warnOnUnassignedImports: true|false`:

* default: `false`
- default: `false`

Warns when unassigned imports are out of order. These warning will not be fixed
Warns when unassigned imports are out of order. These warning will not be fixed
with `--fix` because unassigned imports are used for side-effects and changing the
import of order of modules with side effects can not be done automatically in a
way that is safe.
Expand All @@ -269,18 +300,18 @@ This will fail the rule check:

```js
/* eslint import/order: ["error", {"warnOnUnassignedImports": true}] */
import fs from 'fs';
import './styles.css';
import path from 'path';
import fs from "fs";
import "./styles.css";
import path from "path";
```

While this will pass:

```js
/* eslint import/order: ["error", {"warnOnUnassignedImports": true}] */
import fs from 'fs';
import path from 'path';
import './styles.css';
import fs from "fs";
import path from "path";
import "./styles.css";
```

## Related
Expand All @@ -290,5 +321,4 @@ import './styles.css';
- [`import/internal-regex`] setting

[`import/external-module-folders`]: ../../README.md#importexternal-module-folders

[`import/internal-regex`]: ../../README.md#importinternal-regex

0 comments on commit 0eb0136

Please sign in to comment.