ESLint Import Resolver for Node Modules

0.3.10 · maintenance · verified Sun Apr 19

eslint-import-resolver-node is a foundational package that provides Node.js-style module resolution for `eslint-plugin-import`. It enables ESLint to accurately locate imported modules, respecting standard Node.js resolution rules, including looking into `node_modules` directories, and honoring `package.json`'s `main` field. The current stable version, `0.3.10`, was last published in February 2021. Despite its infrequent updates, it is highly stable and widely adopted, functioning as a core component of the `eslint-plugin-import` ecosystem. Its primary differentiation lies in its direct emulation of Node's native resolution algorithm, which ensures consistent linting behavior with the runtime environment. The resolver supports customization through options such as `extensions`, `paths` (similar to `NODE_PATH`), and `moduleDirectory` for defining alternate `node_modules` locations or source roots.

Common errors

```
ESLint: Unable to resolve path to module 'my-local-component'. (import/no-unresolved)
```
cause The imported module path is not resolvable by Node.js's default module resolution algorithm, often because it's a custom alias or a path not relative to `node_modules`.

fix Add the directory containing 'my-local-component' to the `paths` array in your `eslint-import-resolver-node` configuration. Example: `settings['import/resolver'].node.paths: ['src', 'app']`.
```
ESLint: Unable to resolve path to module 'my-file.jsx'. (import/no-unresolved)
```
cause The module uses a file extension (e.g., `.jsx`, `.ts`, `.vue`) that is not included in the resolver's configured `extensions` list.

fix Add the missing file extension to the `extensions` array in your `eslint-import-resolver-node` configuration. Remember to re-add `.js` if you are overwriting the default. Example: `settings['import/resolver'].node.extensions: ['.js', '.jsx', '.ts', '.tsx']`.
```
Resolve error: unable to load resolver "node".
```
cause The `eslint-import-resolver-node` package is not installed or is not accessible in the current project's `node_modules`.

fix Ensure the package is installed: `npm install eslint-import-resolver-node eslint-plugin-import --save-dev` or `yarn add -D eslint-import-resolver-node eslint-plugin-import`.

Warnings

gotcha When configuring the `extensions` option for `eslint-import-resolver-node`, the default `['.js']` extension is overwritten and must be explicitly re-added if desired. Failure to do so will prevent resolution of `.js` files.
Fix: Always include `'.js'` (and `'.jsx'`, `'.ts'`, etc., as needed) in the `extensions` array if you define this setting. Example: `extensions: ['.js', '.jsx', '.ts', '.tsx']`.
gotcha The `exports` field in `package.json` for Node.js modules might not be fully or consistently supported by `eslint-import-resolver-node` (v0.3.10). This can lead to `import/no-unresolved` errors even when Node.js itself resolves the paths correctly, especially with newer `exports` map features introduced in Node.js modules.
Fix: For projects heavily relying on `package.json`'s `exports` field, consider using `eslint-import-resolver-exports` in conjunction with `eslint-import-resolver-node`. `eslint-import-resolver-exports` is specifically designed to handle `exports` maps.
gotcha While `eslint-import-resolver-node` is a stable and essential component, its own package (v0.3.10, last published 2021) is not actively developed with new features at the same pace as `eslint-plugin-import` itself (v2.x.x). Users should be aware that resolver-specific features or bug fixes might be slow to arrive, but it generally remains compatible due to its core Node.js resolution logic.
Fix: Recognize that `eslint-import-resolver-node` is in a maintenance-like state, prioritizing stability. For advanced resolution needs (e.g., TypeScript paths, Webpack aliases), pair it with other specialized resolvers like `eslint-import-resolver-typescript` or `eslint-import-resolver-alias`.
breaking With ESLint v9 and its new Flat Config system, the way resolvers are configured hasn't fundamentally changed, but the overall ESLint config file structure is now JavaScript objects instead of JSON/YAML. While `eslint-import-resolver-node` remains compatible, the migration to `eslint.config.js` requires updating the configuration syntax.
Fix: Migrate your `.eslintrc.*` configuration to `eslint.config.js`. Ensure your `settings['import/resolver'].node` block is correctly embedded within the new JavaScript object structure. Consult the ESLint v9 migration guide for detailed instructions.

Install

npm install eslint-import-resolver-node npm
yarn add eslint-import-resolver-node yarn
pnpm add eslint-import-resolver-node pnpm

Imports

node

wrong:

import nodeResolver from 'eslint-import-resolver-node'; // This package is not directly imported into JavaScript application code.

correct:

// .eslintrc.js
module.exports = {
  settings: {
    'import/resolver': {
      node: {
        extensions: ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'],
        paths: ['src', 'app'], // Custom paths for resolving modules
      },
    },
  },
  // ... other ESLint configuration
};

The resolver is configured within the `settings` object of your ESLint configuration file (e.g., `.eslintrc.js` or `eslint.config.js` for Flat Config) under the `import/resolver` key. It is not a runtime dependency to be imported in source code. For ESLint v9+ Flat Config, resolvers are configured similarly within the `settings` property of a config object.

Shorthand Node Resolver
wrong:
```
const resolver = require('eslint-import-resolver-node'); // Incorrect for direct use in application code.
```
correct:
```
{
  "settings": {
    "import/resolver": "node"
  }
}
```
For default Node.js resolution without custom options, `eslint-import-resolver-node` can be specified as a string `"node"` under `settings['import/resolver']`.

Quickstart

This quickstart demonstrates a typical `.eslintrc.cjs` configuration using `eslint-import-resolver-node` to handle module resolution for `eslint-plugin-import`. It explicitly sets up common file extensions and custom module paths, which are frequent requirements in modern projects. It also includes basic `eslint-plugin-import` rules to highlight its interaction.

// .eslintrc.cjs (for CommonJS or mixed projects, or .eslintrc.js)
const path = require('node:path');

module.exports = {
  root: true,
  env: {
    browser: true,
    es2021: true,
    node: true,
  },
  extends: [
    'eslint:recommended',
    'plugin:import/recommended',
    // If using TypeScript, also extend 'plugin:import/typescript'
  ],
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module',
  },
  settings: {
    'import/resolver': {
      node: {
        // Explicitly list extensions, including common ones like .js, .jsx, .ts, .tsx
        // If this is set, default '.js' is *not* included automatically.
        extensions: ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.json'],
        // Define custom paths for module resolution, similar to NODE_PATH
        paths: [path.resolve(__dirname, 'src'), path.resolve(__dirname, 'lib')],
        // Define alternative module directories (e.g., 'bower_components')
        moduleDirectory: ['node_modules', 'bower_components']
      },
      // If using TypeScript, also add the TypeScript resolver
      // typescript: {
      //   alwaysTryTypes: true, // Always try to resolve types for TS files
      // },
    },
    'import/extensions': ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'], // Extensions for eslint-plugin-import rules
  },
  plugins: [
    'import',
    // If using TypeScript: '@typescript-eslint'
  ],
  rules: {
    'no-unused-vars': 'warn',
    'import/no-unresolved': ['error', { commonjs: true, amd: true }],
    'import/named': 'error',
    'import/namespace': 'error',
    'import/default': 'error',
    'import/export': 'error',
  },
};

view raw JSON →