eslint-plugin-import-alias

1.2.0 verified Sat Apr 25 auth: no javascript

An ESLint plugin that enforces the use of import path aliases instead of relative imports, helping maintain clean and consistent import structures in JavaScript/TypeScript projects. Version 1.2.0 is the latest stable release with no recent updates; it uses regex-based path matching to replace resolved file paths with aliases like '@src' or '@test'. Compared to similar tools like eslint-plugin-import's 'no-relative-parent-imports' rule, this plugin allows more flexible alias configuration with optional relative depth control and capture groups. It requires eslint as a peer dependency and works with both CJS and ESM configurations.

Common errors

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

cause Plugin is not installed.

fix

Run npm install --save-dev eslint-plugin-import-alias.

error Configuration for rule 'import-alias/import-alias' is invalid: Value has unexpected property 'foo'. ↓

cause Invalid option passed to rule configuration.

fix

Remove unknown properties; valid options are 'aliases', 'relativeDepth', and 'rootDir'.

error TypeError: Cannot read property 'someProperty' of undefined ↓

cause Alias matcher regex may be malformed or parsing error.

fix

Check that 'matcher' is a valid regex string (e.g., '^src') and that the alias object is properly formed.

error Error: ENOENT: no such file or directory, access '/absolute/path/to/project' ↓

cause rootDir points to a non-existent directory.

fix

Set rootDir to a valid absolute path, e.g., __dirname or process.cwd().

Warnings

gotcha Alias matcher regex is applied to the resolved absolute path from rootDir, not the import path itself. ↓

fix Ensure your regex matches the start of the resolved path (e.g., '^src' for paths like '/project/src/...').

gotcha Setting relativeDepth to 0 disallows all relative imports, including './file' and '../file'. ↓

fix If you want to allow same-folder imports, set relativeDepth to 1 or higher.

gotcha The plugin does not autofix imports; it only reports errors. ↓

fix Use a tool like eslint-plugin-import's 'import/order' with path groups or custom codemods to auto-replace relative imports.

deprecated ESLint flat config (eslint.config.js) requires wrapping the plugin differently. ↓

fix Use `import eslintPluginImportAlias from 'eslint-plugin-import-alias'` then spread its configs if available, or manually specify rules.

breaking No known breaking changes, but minor version 1.2.0 may have introduced stricter validation of alias objects. ↓

fix Ensure each alias object has exactly 'alias' (string) and 'matcher' (string regex).

Install

npm install eslint-plugin-import-alias

yarn add eslint-plugin-import-alias

pnpm add eslint-plugin-import-alias

Imports

rules

wrong

Direct require of the plugin without configuration

correct

Define in .eslintrc or eslint.config.js under 'rules' property

The plugin exports a single rule 'import-alias/import-alias' that must be configured with options.

default

wrong

Using require('eslint-plugin-import-alias') and manually registering rules

correct

Add 'import-alias' to 'plugins' array in ESLint config (e.g., plugins: ['import-alias'] for v8 config format)

As a standard ESLint plugin, it is loaded by specifying the plugin name; no imports needed in code.

ImportAliasRule
wrong
```
Importing from 'eslint-plugin-import-alias' expecting types
```
correct
```
No TypeScript type export available
```
This package does not ship TypeScript typings. Users must create their own or use @types/eslint.

Quickstart

Shows ESLint config enabling the import-alias rule with alias configuration for '@src' and '@test'.

// .eslintrc.js
module.exports = {
  plugins: ['import-alias'],
  rules: {
    'import-alias/import-alias': ['error', {
      relativeDepth: 0,
      aliases: [
        { alias: '@src', matcher: '^src' },
        { alias: '@test', matcher: '^test/unit' }
      ]
    }]
  }
};

// Example file: src/app.js
import { helper } from '@src/utils'; // valid
import { helper } from './utils'; // error (relativeDepth: 0)