Registry / testing / eslint-plugin-import-alias

eslint-plugin-import-alias

library1.2.0jsnpmunverified

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.

testing devops

npm install eslint-plugin-import-alias

github ↗package ↗

INSTALL

IMPORT

SIG · ESLINT-PLUGIN-IMPO

eslint-plugin-import-alias

testingjavascriptv1.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

rules

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

✗ Direct require of the plugin without configuration

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

default

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

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

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

ImportAliasRule

✓ No TypeScript type export available

✗ Importing from 'eslint-plugin-import-alias' expecting types

This package does not ship TypeScript typings. Users must create their own or use @types/eslint.

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)

Debug

Known issues

gotchaAlias 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/...').

affects: >=1.0.0

gotchaSetting 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.

affects: >=1.0.0

gotchaThe 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.

affects: >=1.0.0

deprecatedESLint 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.

affects: >=1.2.0

breakingNo 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).

affects: >=1.2.0

Errors

Common errors & fixes

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

Plugin is not installed.

fix

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

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

Invalid option passed to rule configuration.

fix

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

TypeError: Cannot read property 'someProperty' of undefined

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: ENOENT: no such file or directory, access '/absolute/path/to/project'

rootDir points to a non-existent directory.

fix

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

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

eslintrequiredpeer dependency required for ESLint plugin functionality

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/steelsojka/eslint-import-alias ↗

packagehttps://www.npmjs.com/package/eslint-plugin-import-alias ↗