Skip to main content
Version: 7.0.0

Custom Resolvers

This guide explains how to configure custom module resolvers so that eslint-plugin-boundaries resolves imports the same way your bundler does. Different projects use different module systems, bundlers, and path-alias strategies. As the eslint-plugin-import documentation puts it, "it's not always obvious where import x from 'module' should look to find the file behind module".

To handle this, eslint-plugin-boundaries reuses the resolver infrastructure of eslint-plugin-import (through the eslint-module-utils/resolve module), giving you access to a wide ecosystem of resolvers.

How It Works​

The plugin uses eslint-module-utils/resolve internally. Configure module resolution with the import/resolver setting, and eslint-plugin-boundaries respects those same resolution rules.

Deprecated

boundaries/alias is kept for backward compatibility but is deprecated and will be removed in a future major version. Use import/resolver instead.

It keeps working without changes; you will see a deprecation warning in your console. Migrate by moving your path aliases from boundaries/alias to a resolver configuration (for example, the Alias Resolver shown below).

Resolution affects module origin

The resolver outcome decides each dependency's module origin. A resolved import that points inside your project is classified as "local"; one resolved into node_modules is "external". When no configured resolver can resolve an import, the plugin classifies it as "external" by default (unresolvableAlias, see boundaries/flag-as-external). Configuring the right resolver avoids false positives in policies that match on to.module.origin.

Common Resolvers​

Node Resolver​

The default Node.js module resolution algorithm. If you use the legacy .eslintrc configuration, this resolver is active by default. With flat config (eslint.config.js), no resolver is active automatically, so configure it explicitly if you need it:

export default [{
  settings: {
    "import/resolver": {
      node: {
        extensions: [".js", ".jsx", ".json"]
      }
    }
  }
}];

TypeScript Resolver​

For TypeScript projects with path mappings (see TypeScript Support for full details):

npm i eslint-import-resolver-typescript --save-dev
export default [{
  settings: {
    "import/resolver": {
      typescript: {
        alwaysTryTypes: true,
        project: "./tsconfig.json"
      }
    }
  }
}];

Webpack Resolver​

For projects using Webpack with custom resolve configurations:

npm i eslint-import-resolver-webpack --save-dev
export default [{
  settings: {
    "import/resolver": {
      webpack: {
        config: "webpack.config.js"
      }
    }
  }
}];

Alias Resolver​

For custom path aliases without a bundler:

npm i eslint-import-resolver-alias --save-dev
export default [{
  settings: {
    "import/resolver": {
      alias: {
        map: [
          ["@components", "./src/components"],
          ["@utils", "./src/utils"]
        ],
        extensions: [".js", ".jsx", ".json"]
      }
    }
  }
}];

Multiple Resolvers​

You can configure multiple resolvers simultaneously. The plugin tries each resolver in order until one successfully resolves the module:

export default [{
  settings: {
    "import/resolver": {
      node: {},
      typescript: {
        alwaysTryTypes: true
      },
      webpack: {
        config: "webpack.config.js"
      }
    }
  }
}];

Here are some commonly used resolver packages you can install:

Learn More​

For comprehensive information about available resolvers and their configuration options, see the Resolvers documentation in the eslint-plugin-import repository.

Troubleshooting​

Imports not resolving correctly​

  • Ensure the resolver package is installed
  • Check that resolver configuration matches your project setup
  • Verify file extensions are included in the resolver config
  • Try adding the Node.js resolver as a fallback

Imports classified as external unexpectedly​

If a policy that matches on to.module.origin flags a local import as external, the import is probably not resolving. Unresolvable imports are classified as "external" by default (unresolvableAlias in boundaries/flag-as-external). Configure the resolver that recognizes your aliases, then re-run with debug mode to confirm the new origin.

Custom resolver not found​

  • Install the resolver package: npm i --save-dev resolver-package-name
  • Check the package name in your ESLint config
  • Verify the resolver package supports your ESLint version

Further Reading​

  • Settings - the import/resolver and boundaries/flag-as-external settings.
  • Selectors - matching dependencies by module origin and source.
  • TypeScript Support - the TypeScript resolver and path aliases.
  • Monorepo Setup - resolution across workspace packages.
  • Debugging - inspect how each import is resolved and classified.