no-restricted-imports

A project often has modules that some code shouldn't import, like a package that's been replaced, a Node.js module in code that also runs in the browser, or another package's internal files. This rule reports an import of them, and an export ... from as well.

The rule does nothing until you give it options. Like ESLint, it doesn't check require() or import(). With an oxlint config it does check import(), because oxlint's version of the rule does.

Configure

Off by default. To turn it on:

[lint.rules]
"no-restricted-imports" = "error" # or "warn"

Every option, set to its default. The ones that are commented out are unset by default.

[lint.rules]
"no-restricted-imports" = ["error", {
  # paths = <list of strings or objects>,
  # patterns = <list of strings or list of objects>,
}]

Examples

[lint.rules]
no-restricted-imports = ["error", "moment", {
  name = "lodash",
  message = "Use lodash-es.",
}]

Reported:

import moment from "moment";
export { merge } from "lodash";

Not reported:

import { format } from "date-fns";
export { merge } from "lodash-es";
import debounce from "lodash/debounce";

const moment = await import("moment");

A name must match the whole string, so "lodash" doesn't cover "lodash/debounce". Use a pattern for that.

Options

Each option is a module name or an object from the paths table. To use patterns, pass one object with paths, patterns or both:

[lint.rules]
no-restricted-imports = ["error", {
  paths = ["moment"],
  patterns = ["lodash/*"],
}]

paths

Key	What it does
name	The module, exactly as it's written in the import. Required.
message	Text added to the report.
importNames	Report only these names from the module. "default" is the default import.
allowImportNames	Report every name from the module except these.
allowTypeImports	true allows import type and export type. Default false.

With { name: "react", importNames: ["useLayoutEffect"] }, useState is fine. The * is reported because it gives access to the name:

import { useLayoutEffect, useState } from "react";
import * as React from "react";

With { name: "./database", allowTypeImports: true }:

import type { Row } from "./database";

patterns

A list of strings in .gitignore syntax, where a pattern that starts with ! makes an exception to the ones before it. With an oxlint config they're globs that must match the whole module name.

Or a list of objects:

Key	What it does
group	A list of .gitignore patterns. Each object needs a group or a regex.
regex	A regular expression that's tested against the module name.
caseSensitive	true makes group or regex case sensitive. Default false.
importNames, allowImportNames	As in paths.
importNamePattern	Report only the names that match this regular expression.
allowImportNamePattern	Report every name except the ones that match this regular expression.
message, allowTypeImports	As in paths.

With patterns: ["@acme/billing/*", "!@acme/billing/testing"], this is reported:

import { ledger } from "@acme/billing/internal";

And this isn't:

import { charge } from "@acme/billing";
import { fakeCard } from "@acme/billing/testing";

With patterns: [{ regex: "^\\.\\./\\.\\./", message: "Import from the package root." }]:

import { parse } from "../../shared/parse.js";

With patterns: [{ group: ["./icons/*"], importNamePattern: "^Legacy" }], only LegacyArrow is reported:

import { LegacyArrow, Arrow } from "./icons/arrows.js";