eslint-import-resolver-alias

1.1.2 verified Sat Apr 25 auth: no javascript maintenance

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.

Common errors

error Error: Cannot find module 'eslint-plugin-import' ↓

cause The peer dependency eslint-plugin-import is not installed.

fix

Run 'npm install --save-dev eslint-plugin-import' alongside eslint-import-resolver-alias.

error Alias mapping for '@utils/helper' resolved to './utils/helper' but import '@utils/helper' is not found when expected './utils/helper' ↓

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.

fix

Ensure the target module exists with one of the configured extensions. Or use exact regex pattern ['^@utils$', './utils'] and handle subpath separately.

error TypeError: Cannot destructure property 'map' of 'settings import/resolver alias' as it is undefined. ↓

cause The alias config is missing 'map' property when using object form, but the shorthand array form is used instead.

fix

If using object form, include 'map' key: alias: { map: [...] }. If not, use the shorthand: alias: [...].

error Configuration for rule 'import/no-unresolved' is invalid: Value [ { } ] is not a valid resolver. ↓

cause The resolver configuration is malformed (e.g., empty alias array).

fix

Ensure alias configuration is properly formatted, e.g., alias: { map: [['@', './src']] } or alias: [['@', './src']].

Warnings

gotcha 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. ↓

fix Use [['^helper$', './utils/helper']] for exact match.

gotcha 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', ...]. ↓

fix Order your alias array from most specific to least specific.

gotcha 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. ↓

fix Explicitly set 'extensions' array including '.ts', '.tsx' if needed.

deprecated 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. ↓

fix Consider alternative resolvers like eslint-import-resolver-typescript or eslint-import-resolver-webpack for modern projects.

gotcha 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. ↓

fix Use absolute paths or ensure CWD is project root. Alternatively, connect to Resolve#basedir.

Install

npm install eslint-import-resolver-alias

yarn add eslint-import-resolver-alias

pnpm add eslint-import-resolver-alias

Imports

import/resolver.alias

wrong

module.exports = { settings: { 'import/resolver': { alias: [['@', './src']] } } }

correct

module.exports = { settings: { 'import/resolver': { alias: { map: [['@', './src']], extensions: ['.js', '.ts'] } } } }

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.

import/resolver.alias (shorthand)
wrong
```
module.exports = { settings: { 'import/resolver': { alias: { map: [['@', './src']] } } } }
```
correct
```
module.exports = { settings: { 'import/resolver': { alias: [['@', './src']] } } }
```
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.
import/resolver.alias with type annotations
```
// @ts-check
/** @type {import('eslint').Linter.Config} */
module.exports = { settings: { 'import/resolver': { alias: { map: [['@', './src']] } } } }
```
TypeScript users can add JSDoc type annotations for better IntelliSense, but this resolver does not ship its own types.

Quickstart

Installs the package and configures alias resolution for import statements in ESLint.

npm install --save-dev eslint-plugin-import eslint-import-resolver-alias
# .eslintrc.js
module.exports = {
  settings: {
    'import/resolver': {
      alias: {
        map: [
          ['@components', './src/components'],
          ['@utils', './src/utils'],
        ],
        extensions: ['.js', '.ts', '.tsx', '.jsx', '.json']
      }
    }
  }
};