src/content/docs/linter/rules/no-restricted-imports.mdx
import { Tabs, TabItem } from '@astrojs/starlight/components';
<Tabs> <TabItem label="JavaScript (and super languages)" icon="seti:javascript"> ## Summary - Rule available since: `v1.6.0` - Diagnostic Category: [`lint/style/noRestrictedImports`](/reference/diagnostics#diagnostic-category) - This rule isn't recommended, so you need to enable it. - This rule doesn't have a fix. - The default severity of this rule is [**warning**](/reference/diagnostics#warning). - Sources: - Same as [`no-restricted-imports`](https://eslint.org/docs/latest/rules/no-restricted-imports) - Same as [`@typescript-eslint/no-restricted-imports`](https://typescript-eslint.io/rules/no-restricted-imports){
"linter": {
"rules": {
"style": {
"noRestrictedImports": "error"
}
}
}
}
Disallow specified modules when loaded by import or require.
{
"noRestrictedImports": {
"options": {
"paths": {
"lodash": "Using lodash is not encouraged",
"underscore": "Using underscore is not encouraged"
}
}
}
}
{
"linter": {
"rules": {
"style": {
"noRestrictedImports": {
"options": {
"paths": {
"lodash": "Using lodash is not encouraged.",
"underscore": "",
"import-foo": {
"importNames": [
"Bar"
]
},
"import-bar": {
"allowImportNames": [
"Bar"
]
}
},
"patterns": [
{
"group": [
"import-foo/*",
"!import-foo/bar"
]
}
]
}
}
}
}
}
}
import "lodash";
import "underscore";
import { Bar } from "import-foo";
const underscore = await import("underscore");
const lodash = require("lodash");
import foo from 'import-foo/foo';
import "allowed-import";
const myImport = await import("allowed-import");
const myImport = require("allowed-import");
import foo from 'import-foo';
import bar from 'import-foo/bar';
The rule tries to parse the context of the import to see if only one or more of the allowed import names have been imported from a given module.
All of the following import syntaxes are supported:
import (and re-export) declarationsNormal static ESM import declarations are supported:
// Static `import` declaration:
// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import
import "sideeffect-import";
import * as alias1 from "namespace-import";
import { export1, export2 as alias2, "string-name" as alias3, default as defaultExport /* … */ } from "named-import";
import defaultExport from "default-import";
import defaultExport, * as alias5 from "default+namespace-import";
import defaultExport, { export1 /* … */ } from "default+named-import";
export * from "namespace-import";
export { export1, export2 as alias2, "string-name" as alias3, default as defaultExport /* … */ } from "named-import";
The TypeScript-specific type-only imports are also supported:
// TypeScript-specific type-only `import` declaration:
// https://www.typescriptlang.org/docs/handbook/modules/reference.html#type-only-imports-and-exports
import { type export1, type export2 as alias2, type "string-name" as alias3, type default as defaultExport /* … */ } from "named-import";
import type { export1, export2 as alias2, "string-name" as alias3, default as defaultExport /* … */ } from "named-import";
import type defaultExport from "default-import";
import() callsDynamic ESM import() calls are also supported.
Because the import is performed at runtime, it is not always possible to determine which import names are being used.
Nevertheless, the rule tries to detect the following common usage patterns where the set of imported names is determined statically:
// Dynamic `import()` calls:
// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import
import('sideeffect-import');
await import('sideeffect-import');
// ...using await + destructuring-assignment:
const alias1 = await import('namespace-import');
const { default: defaultExport } = await import('default-import')
const { export1, export2: alias2, "string-name": alias3, default: defaultExport /* … */ } = await import("named-import");
// ...using then() with arrow-function + destructuring parameters:
import('namespace-import').then(alias1 => { /* … */ });
import('namespace-import').then((alias1) => { /* … */ });
import('default-import').then(({ default: defaultExport }) => { /* … */ });
import('named-import').then(({ export1, export2: alias2, "string-name": alias3, default: defaultExport /* … */ }) => { /* … */ });
// ...using then() with function + destructuring parameters:
import('namespace-import').then(function(alias1) { /* … */ });
import('default-import').then(function({ default: defaultExport }) { /* … */ });
import('named-import').then(function({ export1, export2: alias2, "string-name": alias3, default: defaultExport /* … */ }) { /* … */ });
// Standalone `import('...')` calls that appear in some other
// unrecognized context will be treated as a namespace import,
// because the return value of `import('...')` is a namespace object:
myFunction(...args, import("namespace-import"), ...args)
require() callsNodeJS-style require() calls are also supported.
Due to the way require() works, these are always treated as default imports.
// Dynamic `require()` call
const defaultExport = require('default-import');
{
"noRestrictedImports": {
"options": {
"paths": {
"lodash": "Using lodash is not encouraged",
"underscore": "Using underscore is not encouraged"
}
}
}
}
Use the options to specify import paths and/or patterns, including specific import names, that you want to restrict in your source code.
{
"linter": {
"rules": {
"style": {
"noRestrictedImports": {
"options": {
"paths": {
"lodash": "Using lodash is not encouraged",
"underscore": "Using underscore is not encouraged",
"import-foo": {
"importNames": [
"Bar"
],
"message": "Please use Bar from /import-bar/baz/ instead."
},
"import-bar": {
"allowImportNames": [
"Bar"
],
"message": "Please use only Bar from import-bar."
}
}
}
}
}
}
}
}
{
"linter": {
"rules": {
"style": {
"noRestrictedImports": {
"options": {
"patterns": [
{
"group": [
"import-foo/*",
"!import-foo/bar"
]
}
]
}
}
}
}
}
}
pathsAn object that lists the import paths that are either wholly or partially restricted.
The keys of the object are the import paths to restrict, and the values can be:
In the example below, we restrict the two paths services-deprecated and constants, with two particular messages.
Importing services-deprecated will emit the message Use services instead..
Importing constants will emit the message This file will be deleted soon.:
{
"linter": {
"rules": {
"style": {
"noRestrictedImports": {
"options": {
"paths": {
"services-deprecated": {
"message": "Use services instead."
},
"constants": "This file will be deleted soon."
}
}
}
}
}
}
}
import * as namespaceAlias from 'services-deprecated';
import { export1 } from 'constants';
paths.<import>.messageSpecifies the message to be shown when the restricted import is used.
A default message will be generated if message is empty or not specified:
{
"linter": {
"rules": {
"style": {
"noRestrictedImports": {
"options": {
"paths": {
"import-foo": {}
}
}
}
}
}
}
}
import { export1 } from 'import-foo';
paths.<import>.importNamesSpecifies the array of import names that should be explicitly forbidden. The following import name specifiers are supported:
"someIdentifier" (import { someIdentifier } from 'named-import')"default" (import defaultExport from 'default-import')"*" (import * as alias1 from 'namespace-import')"" (import "sideeffect-import")Only one of importNames and allowImportNames must be specified.
{
"linter": {
"rules": {
"style": {
"noRestrictedImports": {
"options": {
"paths": {
"import-foo": {
"importNames": [
"Bar"
],
"message": "Please use Bar from /import-bar/baz/ instead."
}
}
}
}
}
}
}
}
import { Bar } from 'import-foo';
import { Foo } from 'import-foo';
paths.<import>.allowImportNamesSpecifies the set of import names that should be explicitly allowed.
See importNames for the set of supported import name specifiers.
Only one of importNames and allowImportNames must be specified.
{
"linter": {
"rules": {
"style": {
"noRestrictedImports": {
"options": {
"paths": {
"import-bar": {
"allowImportNames": [
"Bar"
]
},
"restrictPackagePrivate": "all"
}
}
}
}
}
}
}
import { Baz } from 'import-bar';
import { Bar } from 'import-bar';
patternsSince v2.2.0
This option allows you to specify multiple modules to restrict using gitignore-style patterns.
groupThe patterns array can also include objects. The group property is used to specify the gitignore-style patterns for restricting modules and the message property is used to specify a custom message.
{
"linter": {
"rules": {
"style": {
"noRestrictedImports": {
"options": {
"patterns": [
{
"group": [
"import-foo/*",
"!import-foo/bar"
],
"message": "import-foo is deprecated, except the modules in import-foo/bar."
}
]
}
}
}
}
}
}
import foo from 'import-foo/foo';
import foo from 'import-foo';
import bar from 'import-foo/bar';
importNamePatternSince v2.2.0
This option allows you to use regex patterns to restrict import names.
{
"linter": {
"rules": {
"style": {
"noRestrictedImports": {
"options": {
"patterns": [
{
"group": [
"import-foo/*"
],
"importNamePattern": "[xyz]"
}
]
}
}
}
}
}
}
import { x } from 'import-foo/foo';
import { foo } from 'import-foo/foo';
invertImportNamePatternSince v2.2.0
If true, the matched patterns in the importNamePattern will be allowed
{
"linter": {
"rules": {
"style": {
"noRestrictedImports": {
"options": {
"patterns": [
{
"group": [
"import-foo/*"
],
"importNamePattern": "[xyz]",
"invertImportNamePattern": true
}
]
}
}
}
}
}
}
import { foo } from 'import-foo/foo';
import { x } from 'import-foo/foo';