{"id":10824,"library":"eslint-import-resolver-node","title":"ESLint Import Resolver for Node Modules","description":"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.","status":"maintenance","version":"0.3.10","language":"javascript","source_language":"en","source_url":"https://github.com/import-js/eslint-plugin-import","tags":["javascript","eslint","eslintplugin","esnext","modules","eslint-plugin-import"],"install":[{"cmd":"npm install eslint-import-resolver-node","lang":"bash","label":"npm"},{"cmd":"yarn add eslint-import-resolver-node","lang":"bash","label":"yarn"},{"cmd":"pnpm add eslint-import-resolver-node","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a resolver specifically designed for use with eslint-plugin-import, providing its module resolution capabilities.","package":"eslint-plugin-import","optional":false},{"reason":"Internally, this resolver leverages the 'resolve' package for its core module resolution logic, and its configuration options are passed directly to 'resolve'.","package":"resolve","optional":false}],"imports":[{"note":"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.","wrong":"import nodeResolver from 'eslint-import-resolver-node'; // This package is not directly imported into JavaScript application code.","symbol":"node","correct":"// .eslintrc.js\nmodule.exports = {\n  settings: {\n    'import/resolver': {\n      node: {\n        extensions: ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'],\n        paths: ['src', 'app'], // Custom paths for resolving modules\n      },\n    },\n  },\n  // ... other ESLint configuration\n};"},{"note":"For default Node.js resolution without custom options, `eslint-import-resolver-node` can be specified as a string `\"node\"` under `settings['import/resolver']`.","wrong":"const resolver = require('eslint-import-resolver-node'); // Incorrect for direct use in application code.","symbol":"Shorthand Node Resolver","correct":"{\n  \"settings\": {\n    \"import/resolver\": \"node\"\n  }\n}"}],"quickstart":{"code":"// .eslintrc.cjs (for CommonJS or mixed projects, or .eslintrc.js)\nconst path = require('node:path');\n\nmodule.exports = {\n  root: true,\n  env: {\n    browser: true,\n    es2021: true,\n    node: true,\n  },\n  extends: [\n    'eslint:recommended',\n    'plugin:import/recommended',\n    // If using TypeScript, also extend 'plugin:import/typescript'\n  ],\n  parserOptions: {\n    ecmaVersion: 'latest',\n    sourceType: 'module',\n  },\n  settings: {\n    'import/resolver': {\n      node: {\n        // Explicitly list extensions, including common ones like .js, .jsx, .ts, .tsx\n        // If this is set, default '.js' is *not* included automatically.\n        extensions: ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.json'],\n        // Define custom paths for module resolution, similar to NODE_PATH\n        paths: [path.resolve(__dirname, 'src'), path.resolve(__dirname, 'lib')],\n        // Define alternative module directories (e.g., 'bower_components')\n        moduleDirectory: ['node_modules', 'bower_components']\n      },\n      // If using TypeScript, also add the TypeScript resolver\n      // typescript: {\n      //   alwaysTryTypes: true, // Always try to resolve types for TS files\n      // },\n    },\n    'import/extensions': ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'], // Extensions for eslint-plugin-import rules\n  },\n  plugins: [\n    'import',\n    // If using TypeScript: '@typescript-eslint'\n  ],\n  rules: {\n    'no-unused-vars': 'warn',\n    'import/no-unresolved': ['error', { commonjs: true, amd: true }],\n    'import/named': 'error',\n    'import/namespace': 'error',\n    'import/default': 'error',\n    'import/export': 'error',\n  },\n};\n","lang":"javascript","description":"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."},"warnings":[{"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']`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<=0.3.10"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.3.0 (when used with ESLint >=9.0.0)"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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']`.","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`.","error":"ESLint: Unable to resolve path to module 'my-local-component'. (import/no-unresolved)"},{"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']`.","cause":"The module uses a file extension (e.g., `.jsx`, `.ts`, `.vue`) that is not included in the resolver's configured `extensions` list.","error":"ESLint: Unable to resolve path to module 'my-file.jsx'. (import/no-unresolved)"},{"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`.","cause":"The `eslint-import-resolver-node` package is not installed or is not accessible in the current project's `node_modules`.","error":"Resolve error: unable to load resolver \"node\"."}],"ecosystem":"npm"}