{"id":18317,"library":"eslint-import-resolver-alias","title":"eslint-import-resolver-alias","description":"A resolver plugin for eslint-plugin-import that adds support for module aliases, custom file extensions, and path mapping. Current stable version is 1.1.2 (last released in 2018). It allows developers to define alias mappings in ESLint configuration so that 'import' statements resolve correctly even when using module aliases or custom extensions. Unlike other resolvers like eslint-import-resolver-webpack or eslint-import-resolver-typescript, this one is lightweight and does not require webpack config; it works purely based on a simple alias map array. It supports Node.js >=4 and requires eslint-plugin-import >=1.4.0 as a peer dependency. The resolver is in maintenance mode with no updates since 2018.","status":"maintenance","version":"1.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/johvin/eslint-import-resolver-alias","tags":["javascript","eslint","eslintplugin","eslint-plugin-import","eslint-import-resolver","import-resolver","resolver","resolve","resolution"],"install":[{"cmd":"npm install eslint-import-resolver-alias","lang":"bash","label":"npm"},{"cmd":"yarn add eslint-import-resolver-alias","lang":"bash","label":"yarn"},{"cmd":"pnpm add eslint-import-resolver-alias","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency: required for the resolver to hook into import resolution.","package":"eslint-plugin-import","optional":false}],"imports":[{"note":"Config object can be either with 'map' and 'extensions' keys, or just an array of mappings (shorthand). The shorthand does not allow specifying custom extensions.","wrong":"module.exports = { settings: { 'import/resolver': { alias: [['@', './src']] } } }","symbol":"import/resolver.alias","correct":"module.exports = { settings: { 'import/resolver': { alias: { map: [['@', './src']], extensions: ['.js', '.ts'] } } } }"},{"note":"If extensions are not specified, you can use the shorthand array form. The object form with 'map' key also works, but the shorthand omits the 'map' object wrapper.","wrong":"module.exports = { settings: { 'import/resolver': { alias: { map: [['@', './src']] } } } }","symbol":"import/resolver.alias (shorthand)","correct":"module.exports = { settings: { 'import/resolver': { alias: [['@', './src']] } } }"},{"note":"TypeScript users can add JSDoc type annotations for better IntelliSense, but this resolver does not ship its own types.","wrong":"","symbol":"import/resolver.alias with type annotations","correct":"// @ts-check\n/** @type {import('eslint').Linter.Config} */\nmodule.exports = { settings: { 'import/resolver': { alias: { map: [['@', './src']] } } } }"}],"quickstart":{"code":"npm install --save-dev eslint-plugin-import eslint-import-resolver-alias\n# .eslintrc.js\nmodule.exports = {\n  settings: {\n    'import/resolver': {\n      alias: {\n        map: [\n          ['@components', './src/components'],\n          ['@utils', './src/utils'],\n        ],\n        extensions: ['.js', '.ts', '.tsx', '.jsx', '.json']\n      }\n    }\n  }\n};","lang":"javascript","description":"Installs the package and configures alias resolution for import statements in ESLint."},"warnings":[{"fix":"Use [['^helper$', './utils/helper']] for exact match.","message":"Alias mappings are matched by prefix, not exact string. For example, mapping ['helper', './utils/helper'] will cause 'helper' or 'helper/*' to resolve to './utils/helper/*', not just 'helper'. Use a regex-like pattern with ^$ to force exact match.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Order your alias array from most specific to least specific.","message":"The order of alias mappings matters: more specific aliases must come before less specific ones. For example, ['material-ui/DatePicker', ...] must come before ['material-ui', ...].","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Explicitly set 'extensions' array including '.ts', '.tsx' if needed.","message":"The 'extensions' property defaults to ['.js', '.json', '.node'] if not specified or set to an empty array. It does NOT include TypeScript extensions by default.","severity":"gotcha","affected_versions":">=1.1.0"},{"fix":"Consider alternative resolvers like eslint-import-resolver-typescript or eslint-import-resolver-webpack for modern projects.","message":"Package is in maintenance mode; no updates since 2018. It may not support newer ESLint versions (ESLint 9+ flat config) or Node.js versions beyond 12.","severity":"deprecated","affected_versions":">=1.1.2"},{"fix":"Use absolute paths or ensure CWD is project root. Alternatively, connect to Resolve#basedir.","message":"Relative alias paths are resolved relative to the current working directory (usually project root), not the file containing the import. This may cause unexpected resolution if ESLint is run from a different directory.","severity":"gotcha","affected_versions":">=1.0.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' alongside eslint-import-resolver-alias.","cause":"The peer dependency eslint-plugin-import is not installed.","error":"Error: Cannot find module 'eslint-plugin-import'"},{"fix":"Ensure the target module exists with one of the configured extensions. Or use exact regex pattern ['^@utils$', './utils'] and handle subpath separately.","cause":"The alias ['@utils', './utils'] matches '@utils/helper' as prefix but resolves to './utils/helper' correctly; but if the actual path is './utils/helper/index.js' or missing extension, it fails.","error":"Alias mapping for '@utils/helper' resolved to './utils/helper' but import '@utils/helper' is not found when expected './utils/helper'"},{"fix":"If using object form, include 'map' key: alias: { map: [...] }. If not, use the shorthand: alias: [...].","cause":"The alias config is missing 'map' property when using object form, but the shorthand array form is used instead.","error":"TypeError: Cannot destructure property 'map' of 'settings import/resolver alias' as it is undefined."},{"fix":"Ensure alias configuration is properly formatted, e.g., alias: { map: [['@', './src']] } or alias: [['@', './src']].","cause":"The resolver configuration is malformed (e.g., empty alias array).","error":"Configuration for rule 'import/no-unresolved' is invalid: Value [ {  } ] is not a valid resolver."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}