eslint-import-resolver-custom-alias

1.3.2 verified Sat Apr 25 auth: no javascript

An ESLint resolver (v1.3.2, 2022) for eslint-plugin-import that enables custom import aliases and file extensions. Unlike other resolvers (e.g., eslint-import-resolver-alias, eslint-import-resolver-webpack), it supports Lerna monorepos via a `packages` config, allowing alias resolution relative to the current package directory. It also supports an empty-string alias to prepend a base path. Requires eslint-plugin-import >=2.2.0 as a peer dependency.

Common errors

error ESLint couldn't find the plugin "eslint-import-resolver-custom-alias" ↓

cause The resolver is not installed or not in node_modules.

fix

Run npm install --dev eslint-import-resolver-custom-alias and ensure it's in devDependencies.

error Unable to resolve path to module 'path/to/module' ↓

cause Alias key not matching the import prefix or alias path invalid.

fix

Check alias keys match imports, and alias values point to existing directories.

error Resolve error: the package alias "@" has been misconfigured ↓

cause Alias object property type mismatch (e.g., using array instead of string for path).

fix

Ensure alias values are strings (relative or absolute paths).

error Configuration for rule 'import/no-unresolved' is invalid: Value "eslint-import-resolver-custom-alias" is invalid ↓

cause Resolver name string missing or incorrectly spelled in settings.

fix

Use exactly: 'eslint-import-resolver-custom-alias' (quoted) in settings.import.resolver.

Warnings

breaking Relative alias values are resolved from process.cwd(), not relative to the file. This might cause unexpected resolution in monorepos without proper `packages` config. ↓

fix Use absolute paths or configure `packages` so the resolver adjusts based on file location.

deprecated Empty string alias behavior is undocumented for nested directories; may change in future versions. ↓

fix Avoid using empty string alias or pin version and test thoroughly.

gotcha The resolver name must exactly match the package name in quotes, e.g., 'eslint-import-resolver-custom-alias'. Misspelling or wrong casing leads to silent fallback to default resolver. ↓

fix Double-check the resolver name in .eslintrc settings.

gotcha Extensions default to ['.js'] only; if your project uses .jsx or .ts, you must explicitly list them. ↓

fix Add .jsx, .ts, .tsx etc. to the `extensions` array.

gotcha Packages glob pattern must be relative to root; absolute paths or complex patterns may not work. ↓

fix Use simple globs like 'packages/*' or 'modules/**' without leading ./

Install

npm install eslint-import-resolver-custom-alias

yarn add eslint-import-resolver-custom-alias

pnpm add eslint-import-resolver-custom-alias

Imports

resolver

wrong

import resolver from 'eslint-import-resolver-custom-alias'

correct

settings: { 'import/resolver': { 'eslint-import-resolver-custom-alias': { ... } } }

Not imported directly; configured in .eslintrc settings. The resolver name must match the package name exactly.

alias

wrong

settings: { 'import/resolver': { 'eslint-import-resolver-custom-alias': { maps: { '@': './src' } } } }

correct

settings: { 'import/resolver': { 'eslint-import-resolver-custom-alias': { alias: { '@': './src' } } } }

The property is `alias`, not `maps`, `map`, or `paths`. No import required.

packages

wrong

settings: { 'import/resolver': { 'eslint-import-resolver-custom-alias': { lerna: true } } }

correct

settings: { 'import/resolver': { 'eslint-import-resolver-custom-alias': { packages: ['packages/*'] } } }

Use `packages` array with glob patterns; no Lerna-specific boolean option.

Quickstart

ESLint config to resolve imports like `@/utils` to `./src/utils` in a Lerna monorepo.

{
  "settings": {
    "import/resolver": {
      "eslint-import-resolver-custom-alias": {
        "alias": {
          "@": "./src"
        },
        "extensions": [".js", ".jsx", ".ts"],
        "packages": ["packages/*"]
      }
    }
  }
}