eslint-plugin-strict-dependencies

1.3.33 verified Sat Apr 25 auth: no javascript

ESLint plugin to enforce custom module dependency rules in TypeScript projects. Current stable version is 1.3.33, released under MIT license. It uses tsconfig paths for alias resolution and supports glob patterns, forward matching, and per-rule allow-lists for import sources. Unlike generic import lint rules, it allows granular control over which modules can import from which paths, including member-level restrictions (e.g., disallowing `Suspense` from `react` except in a specific file). It also offers options like `resolveRelativeImport` to convert relative imports to absolute paths for linting, and `excludeTypeImportChecks` to skip type-only imports. The plugin is actively maintained with regular dependency updates but no major feature changes recently.

Common errors

error Error: Failed to load plugin 'strict-dependencies' declared in '.eslintrc': Cannot find module 'eslint-plugin-strict-dependencies' ↓

cause The plugin is not installed or ESLint cannot resolve it.

fix

Run 'npm install eslint-plugin-strict-dependencies --save-dev' or ensure it is in your package.json.

error Error: Cannot find module 'typescript'. Please install 'typescript' in your project. ↓

cause The plugin uses TypeScript internally to parse tsconfig, but TypeScript is not installed.

fix

Run 'npm install typescript --save-dev' to add TypeScript as a dev dependency.

error Error: Could not find tsconfig.json. Make sure a tsconfig.json file exists in the project root. ↓

cause The plugin requires tsconfig.json to resolve paths, but the file is missing.

fix

Create a tsconfig.json file in your project root, even if minimal, e.g., { "compilerOptions": {} }.

error Parsing error: The keyword 'import' is reserved ↓

cause ESLint is not configured to parse TypeScript. The plugin's rule uses TypeScript AST, but the parser is not set to @typescript-eslint/parser.

fix

Install and configure @typescript-eslint/parser in your ESLint config: 'parser: "@typescript-eslint/parser"'.

Warnings

breaking The plugin requires a tsconfig.json file in the project root. Without it, the rule will not work. ↓

fix Ensure tsconfig.json exists and has the necessary paths compilerOptions (if using alias resolution).

gotcha The rule uses tsconfig paths for alias resolution, but by default uses index 0 of each path array. If your tsconfig has multiple paths in an array (e.g., ['aaa/*', 'bbb/*']), the plugin may resolve to the wrong alias. ↓

fix Use the 'pathIndexMap' option to specify which index to use for each key.

gotcha Relative imports are not resolved by default; they are excluded from linting. This can cause missed violations where a relative import reaches a disallowed module. ↓

fix Set the 'resolveRelativeImport' option to true in the rule options to convert relative imports to absolute paths for linting.

gotcha The 'module' pattern uses glob matching but also supports forward matching (string prefix). This dual behavior may cause unexpected matches if a pattern accidentally matches unintended paths. ↓

fix Always test your patterns and prefer explicit glob patterns (e.g., 'src/modules/**') to avoid ambiguity.

deprecated The 'allowSameModule' option defaults to true in v1.x but may be deprecated in future versions to enforce stricter rules. ↓

fix Explicitly set 'allowSameModule' to the desired value to avoid breaking changes in future releases.

Install

npm install eslint-plugin-strict-dependencies

yarn add eslint-plugin-strict-dependencies

pnpm add eslint-plugin-strict-dependencies

Imports

plugin (default)

wrong

import { strictDependencies } from 'eslint-plugin-strict-dependencies';

correct

import plugin from 'eslint-plugin-strict-dependencies'; // or require('eslint-plugin-strict-dependencies')

The plugin is a default export. When using ESM, import default. When using CommonJS, require the entire module.

strict-dependencies rule

wrong

// Incorrect rule name: "strict-dependencies/rule" or "strict-dependencies/strict-dependency"

correct

// In .eslintrc: "strict-dependencies/strict-dependencies": "error"

The rule key is 'strict-dependencies/strict-dependencies' (plugin name / rule name). The rule name is repeated.

TypeScript type for options
wrong
```
import { Options } from 'eslint-plugin-strict-dependencies';
```
correct
```
import type { Options } from 'eslint-plugin-strict-dependencies';
```
There is currently no TypeScript type export; the plugin is untyped. This import will fail at runtime.

Quickstart

This shows how to configure the plugin to restrict imports: 'src/components/ui' can only be imported from 'src/components/page', and 'next/router' can only be imported from 'src/libs/router.ts'.

// .eslintrc.js
module.exports = {
  plugins: ['strict-dependencies'],
  rules: {
    'strict-dependencies/strict-dependencies': [
      'error',
      [
        {
          module: 'src/components/ui',
          allowReferenceFrom: ['src/components/page'],
          allowSameModule: true,
        },
        {
          module: 'next/router',
          allowReferenceFrom: ['src/libs/router.ts'],
          allowSameModule: false,
        },
      ],
      // optional options
      // {
      //   resolveRelativeImport: true,
      //   pathIndexMap: { '*': 1 }
      // }
    ],
  },
};