Skip to content

feat(ts): implement restrictedImports rule #2196

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kolharsam wants to merge 5 commits into
base: main
Choose a base branch
from
Open

feat(ts): implement restrictedImports rule #2196

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
e71959f
feat: implement restrictedImports rule with tests and documentation
kolharsam Jan 30, 2026
1d9081b
replace any with unknown in restrictedImports.ts
kolharsam Jan 30, 2026
340ca39
reorder restrictedImports import statements in plugin.ts
kolharsam Jan 30, 2026
a39448f
Merge branch 'main' into sam/1999
kolharsam Jan 31, 2026
c9bcab4
format code by adjusting indentation for restrictedImports
kolharsam Jan 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion packages/comparisons/src/data.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16106,7 +16106,8 @@
],
"flint": {
"name": "restrictedImports",
"plugin": "ts"
"plugin": "ts",
"status": "implemented"
},
"oxlint": [
{
Expand Down
144 changes: 144 additions & 0 deletions packages/site/src/content/docs/rules/ts/restrictedImports.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,144 @@
---
description: "Restricts specified modules from being imported."
title: "restrictedImports"
topic: "rules"
---

import { Tabs, TabItem } from "@astrojs/starlight/components";
import { RuleEquivalents } from "~/components/RuleEquivalents";
import RuleSummary from "~/components/RuleSummary.astro";

<RuleSummary plugin="ts" rule="restrictedImports" />

Some modules should not be used in certain parts of a codebase.
This rule allows you to restrict specific modules from being imported, either by exact path or by glob pattern.
It detects static `import` and `export ... from` declarations.

## Examples

<Tabs>
<TabItem label="❌ Incorrect">

```ts
// With paths: ["lodash"]
import _ from "lodash";

// With paths: [{ name: "utils", importNames: ["dangerousHelper"] }]
import { dangerousHelper } from "utils";

// With patterns: ["internal/*"]
import { secret } from "internal/auth";
```

</TabItem>
<TabItem label="✅ Correct">

```ts
// With paths: ["lodash"]
import { pick } from "lodash-es";

// With paths: [{ name: "utils", importNames: ["dangerousHelper"] }]
import { safeHelper } from "utils";

// With patterns: ["internal/*"]
import { auth } from "external/auth";
```

</TabItem>
</Tabs>

## Options

### `paths`

- Type: `Array<string | PathConfig>`
- Default: `[]`

Exact module specifiers to restrict.
Each entry can be a simple string or a configuration object.

```jsonc
{
"paths": [
// Simple: restrict the entire module
"lodash",

// Advanced: restrict specific imports
{
"name": "utils",
"importNames": ["dangerousHelper"],
"message": "Use safeHelper instead.",
},

// Allow only certain imports
{
"name": "react",
"allowImportNames": ["useState", "useEffect"],
},

// Allow type-only imports
{
"name": "internal-types",
"allowTypeImports": true,
},
],
}
```

**PathConfig fields:**

| Field | Type | Description |
| ------------------ | ----------- | --------------------------------------------------------------- |
| `name` | `string` | The module specifier to restrict. |
| `message` | `string?` | Custom message shown when the import is restricted. |
| `importNames` | `string[]?` | Only these specific import names are restricted. |
| `allowImportNames` | `string[]?` | Only these import names are allowed; all others are restricted. |
| `allowTypeImports` | `boolean?` | Whether type-only imports are exempt from the restriction. |

### `patterns`

- Type: `Array<string | PatternConfig>`
- Default: `[]`

Glob patterns to match restricted module specifiers.

```jsonc
{
"patterns": [
// Simple: restrict by glob
"internal/*",

// Advanced: restrict with options
{
"group": ["legacy/**", "deprecated/**"],
"message": "These modules are deprecated. Use the new API.",
"allowTypeImports": true,
},
],
}
```

**PatternConfig fields:**

| Field | Type | Description |
| ------------------ | ----------- | --------------------------------------------------------------- |
| `group` | `string[]` | Glob patterns to match module specifiers against. |
| `message` | `string?` | Custom message shown when a matching import is restricted. |
| `importNames` | `string[]?` | Only these specific import names are restricted. |
| `allowImportNames` | `string[]?` | Only these import names are allowed; all others are restricted. |
| `allowTypeImports` | `boolean?` | Whether type-only imports are exempt from the restriction. |

## 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 `paths` or `patterns` options.
You might consider using [Flint disable comments](/directives) and/or [configuration file disables](/configuration#files) for specific situations instead of completely disabling this rule.

## Further Reading

- [ESLint `no-restricted-imports`](https://eslint.org/docs/latest/rules/no-restricted-imports)
- [TypeScript-ESLint `no-restricted-imports`](https://typescript-eslint.io/rules/no-restricted-imports)

## Equivalents in Other Linters

<RuleEquivalents pluginId="ts" ruleId="restrictedImports" />
2 changes: 2 additions & 0 deletions packages/ts/src/plugin.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -241,6 +241,7 @@ import regexUnusedLazyQuantifiers from "./rules/regexUnusedLazyQuantifiers.ts";
import regexUnusedQuantifiers from "./rules/regexUnusedQuantifiers.ts";
import regexValidity from "./rules/regexValidity.ts";
import regexWordMatchers from "./rules/regexWordMatchers.ts";
import restrictedImports from "./rules/restrictedImports.ts";
import returnAssignments from "./rules/returnAssignments.ts";
import selfAssignments from "./rules/selfAssignments.ts";
import sequences from "./rules/sequences.ts";
Expand Down Expand Up @@ -527,6 +528,7 @@ export const ts = createPlugin({
regexUnusedQuantifiers,
regexValidity,
regexWordMatchers,
restrictedImports,
returnAssignments,
selfAssignments,
sequences,
Expand Down
Loading