noRestrictedImports

JavaScript (and super languages)

Summary

• Rule available since: v1.6.0
• Diagnostic Category: lint/style/noRestrictedImports
• This rule doesn’t have a fix.
• The default severity of this rule is warning.
• Sources:
  • Same as no-restricted-imports
  • Same as @typescript-eslint/no-restricted-imports

Description

Disallow specified modules when loaded by import or require.

Examples

{
    "noRestrictedImports": {
        "options": {
            "paths": {
                "lodash": "Using lodash is not encouraged",
                "underscore": "Using underscore is not encouraged"
            }
        }
    }
}

{
    "options": {
        "paths": {
            "lodash": "Using lodash is not encouraged.",
            "underscore": "",
            "import-foo": { "importNames": ["Bar"] },
            "import-bar": { "allowImportNames": ["Bar"] }
        }
    }
}

Invalid

import "lodash";
import "allowed-import";

const underscore = await import("underscore");

const lodash = require("lodash");

Valid

import "allowed-import";
const myImport = await import("allowed-import");
const myImport = require("allowed-import");

Supported Import Syntaxes

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:

Static import (and re-export) declarations

Normal 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";

Dynamic import() calls

Dynamic 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)

Dynamic require() calls

NodeJS-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');

Options

{
    "noRestrictedImports": {
        "options": {
            "paths": {
                "lodash": "Using lodash is not encouraged",
                "underscore": "Using underscore is not encouraged"
            }
        }
    }
}

Use the options to specify the import paths and/or specific import names within them that you want to restrict in your source code.

{
    "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."
            }
        }
    }
}

paths

An 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:

• A string with a custom message to show in the diagnostic when any
• An object with additional options, as explained below.

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.:

{
    "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>.message

Specifies the message to be shown when the restricted import is used.

A default message will be generated if message is empty or not specified:

{
    "options": {
        "paths": {
            "import-foo": { }
        }
    }
}

import { export1 } 'import-foo';

code-block.js:1:20 parse ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ expected from but instead found 'import-foo'
  
  > 1 │ import { export1 } ‘import-foo’;
      │                    ^^^^^^^^^^^^
    2 │ 
  
  ℹ Remove ‘import-foo’
  

paths.<import>.importNames

Specifies the array of import names that should be explicitly forbidden. The following import name specifiers are supported:

• Named import: "someIdentifier" (import { someIdentifier } from 'named-import')
• Default import: "default" (import defaultExport from 'default-import')
• Namespace import: "*" (import * as alias1 from 'namespace-import')
• Side effect/Bare import: "" (import "sideeffect-import")

Only one of importNames and allowImportNames must be specified.

{
    "options": {
        "paths": {
            "import-foo": {
                "importNames": ["Bar"],
                "message": "Please use Bar from /import-bar/baz/ instead."
            }
        }
    }
}

Invalid

import { Bar } from 'import-foo';

Valid

import { Foo } from 'import-foo';

paths.<import>.allowImportNames

Specifies 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.

{
    "options": {
        "paths": {
            "import-bar": {
              "allowImportNames": ["Bar"]
            },
            "restrictPackagePrivate": "all"
        }
    }
}

Invalid

import { Baz } from 'import-bar';

Valid

import { Bar } from 'import-bar';

How to configure

biome.json

{
  "linter": {
    "rules": {
      "style": {
        "noRestrictedImports": "error"
      }
    }
  }
}

Related links

• Disable a rule
• Configure the code fix
• Rule options