{"id":19787,"library":"eslint-plugin-import-alias","title":"eslint-plugin-import-alias","description":"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.","status":"active","version":"1.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/steelsojka/eslint-import-alias","tags":["javascript"],"install":[{"cmd":"npm install eslint-plugin-import-alias","lang":"bash","label":"npm"},{"cmd":"yarn add eslint-plugin-import-alias","lang":"bash","label":"yarn"},{"cmd":"pnpm add eslint-plugin-import-alias","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency required for ESLint plugin functionality","package":"eslint","optional":false}],"imports":[{"note":"The plugin exports a single rule 'import-alias/import-alias' that must be configured with options.","wrong":"Direct require of the plugin without configuration","symbol":"rules","correct":"Define in .eslintrc or eslint.config.js under 'rules' property"},{"note":"As a standard ESLint plugin, it is loaded by specifying the plugin name; no imports needed in code.","wrong":"Using require('eslint-plugin-import-alias') and manually registering rules","symbol":"default","correct":"Add 'import-alias' to 'plugins' array in ESLint config (e.g., plugins: ['import-alias'] for v8 config format)"},{"note":"This package does not ship TypeScript typings. Users must create their own or use @types/eslint.","wrong":"Importing from 'eslint-plugin-import-alias' expecting types","symbol":"ImportAliasRule","correct":"No TypeScript type export available"}],"quickstart":{"code":"// .eslintrc.js\nmodule.exports = {\n  plugins: ['import-alias'],\n  rules: {\n    'import-alias/import-alias': ['error', {\n      relativeDepth: 0,\n      aliases: [\n        { alias: '@src', matcher: '^src' },\n        { alias: '@test', matcher: '^test/unit' }\n      ]\n    }]\n  }\n};\n\n// Example file: src/app.js\nimport { helper } from '@src/utils'; // valid\nimport { helper } from './utils'; // error (relativeDepth: 0)","lang":"javascript","description":"Shows ESLint config enabling the import-alias rule with alias configuration for '@src' and '@test'."},"warnings":[{"fix":"Ensure your regex matches the start of the resolved path (e.g., '^src' for paths like '/project/src/...').","message":"Alias matcher regex is applied to the resolved absolute path from rootDir, not the import path itself.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If you want to allow same-folder imports, set relativeDepth to 1 or higher.","message":"Setting relativeDepth to 0 disallows all relative imports, including './file' and '../file'.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use a tool like eslint-plugin-import's 'import/order' with path groups or custom codemods to auto-replace relative imports.","message":"The plugin does not autofix imports; it only reports errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use `import eslintPluginImportAlias from 'eslint-plugin-import-alias'` then spread its configs if available, or manually specify rules.","message":"ESLint flat config (eslint.config.js) requires wrapping the plugin differently.","severity":"deprecated","affected_versions":">=1.2.0"},{"fix":"Ensure each alias object has exactly 'alias' (string) and 'matcher' (string regex).","message":"No known breaking changes, but minor version 1.2.0 may have introduced stricter validation of alias objects.","severity":"breaking","affected_versions":">=1.2.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run `npm install --save-dev eslint-plugin-import-alias`.","cause":"Plugin is not installed.","error":"Error: Failed to load plugin 'import-alias' declared in '.eslintrc': Cannot find module 'eslint-plugin-import-alias'"},{"fix":"Remove unknown properties; valid options are 'aliases', 'relativeDepth', and 'rootDir'.","cause":"Invalid option passed to rule configuration.","error":"Configuration for rule 'import-alias/import-alias' is invalid: Value has unexpected property 'foo'."},{"fix":"Check that 'matcher' is a valid regex string (e.g., '^src') and that the alias object is properly formed.","cause":"Alias matcher regex may be malformed or parsing error.","error":"TypeError: Cannot read property 'someProperty' of undefined"},{"fix":"Set rootDir to a valid absolute path, e.g., __dirname or process.cwd().","cause":"rootDir points to a non-existent directory.","error":"Error: ENOENT: no such file or directory, access '/absolute/path/to/project'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}