restrictedImports

Restricts specified modules from being imported.

✅ This rule is included in the ts preset.

Over time, many codebases develop restrictions on which modules can be imported in which areas. This rule allows you to restrict specific modules from being imported using TypeOrValueSpecifier to identify targets.

Examples

❌ Incorrect

// With restrictions: [{ specifier: { from: "package", package: "lodash" } }]
import _ from "lodash";

// With restrictions: [{ specifier: { from: "package", name: "useState", package: "react" } }]
import { useState } from "react";

// With restrictions: [{ specifier: { from: "file", path: "./internal/secret.ts" } }]
import { secret } from "./internal/secret";

✅ Correct

// With restrictions: [{ specifier: { from: "package", package: "lodash" } }]
import { pick } from "lodash-es";

// With restrictions: [{ specifier: { from: "package", name: "useState", package: "react" } }]
import { useEffect } from "react";

// With restrictions: [{ specifier: { from: "file", path: "./internal/secret.ts" }, allowTypeImports: true }]
import type { SecretType } from "./internal/secret";

Options

restrictions

• Type: Array<Restriction>
• Default: []

Each restriction identifies an import target using a TypeOrValueSpecifier and optional metadata.

{
  "restrictions": [
    // Restrict a specific export from a package
    {
      "specifier": {
        "from": "package",
        "name": "useState",
        "package": "react",
      },
      "message": "Use our custom useStateWrapper instead.",
    },

    // Restrict an entire package
    {
      "specifier": { "from": "package", "package": "lodash" },
      "message": "Use lodash-es for tree-shaking.",
    },

    // Restrict a local file, but allow type-only imports
    {
      "specifier": {
        "from": "file",
        "path": "./src/internal/secret.ts",
      },
      "allowTypeImports": true,
    },

    // Restrict a built-in lib type
    {
      "specifier": { "from": "lib", "name": "eval" },
    },
  ],
}

Restriction fields:

| Field | Type | Description | | ------------------ | ---------------------- | ---------------------------------------------------------- | | specifier | TypeOrValueSpecifier | Identifies the restricted import target (see below). | | message | string? | Custom message shown when the restriction is triggered. | | allowTypeImports | boolean? | Whether type-only imports are exempt from the restriction. |

TypeOrValueSpecifier shapes:

| Variant | Fields | Description | | --------- | -------------------------- | ------------------------------------------------ | | package | from, package, name? | Matches exports from an npm package. | | file | from, path?, name? | Matches exports from a local file. | | lib | from, name? | Matches exports from TypeScript's built-in libs. |

When name is omitted, all exports from the matched source are restricted. When name is provided (as a string or array of strings), only those specific exports are restricted.

Relationship to TypeOrValueSpecifier

This rule uses the TypeOrValueSpecifier config shape from @typescript-eslint/type-utils — same from discriminator ("file", "lib", "package") and field names (name, path, package).

One deviation: name is optional here (omitting it restricts all exports from the source), whereas typescript-eslint's TypeOrValueSpecifier requires name. This enables whole-module restrictions like { from: "package", package: "lodash" }.

When Not To Use It

If you do not need to restrict any modules from being imported, you do not need this rule. This rule requires explicit configuration to do anything, so it has no effect without restrictions.

Equivalents in Other Linters

• Biome: noRestrictedImports
• ESLint: no-restricted-imports@typescript-eslint/no-restricted-imports
• Oxlint: eslint/no-restricted-imports