Registry /
testing / eslint-import-resolver-node
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
node
✓ // .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
};
✗ import nodeResolver from 'eslint-import-resolver-node'; // This package is not directly imported into JavaScript application code.
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
✓ {
"settings": {
"import/resolver": "node"
}
}
✗ const resolver = require('eslint-import-resolver-node'); // Incorrect for direct use in application code.
For default Node.js resolution without custom options, `eslint-import-resolver-node` can be specified as a string `"node"` under `settings['import/resolver']`.
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',
},
};
Debug
Known issues
gotchaWhen 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.fixAlways include `'.js'` (and `'.jsx'`, `'.ts'`, etc., as needed) in the `extensions` array if you define this setting. Example: `extensions: ['.js', '.jsx', '.ts', '.tsx']`.
affects: >=0.1.0
gotchaThe `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.fixFor 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.
affects: <=0.3.10
gotchaWhile `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.fixRecognize 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`.
affects: All versions
breakingWith 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.fixMigrate 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.
affects: >=0.3.0 (when used with ESLint >=9.0.0)
Errors
Common errors & fixes
ESLint: Unable to resolve path to module 'my-local-component'. (import/no-unresolved)
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`.
fixAdd 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)
The module uses a file extension (e.g., `.jsx`, `.ts`, `.vue`) that is not included in the resolver's configured `extensions` list.
fixAdd 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".
The `eslint-import-resolver-node` package is not installed or is not accessible in the current project's `node_modules`.
fixEnsure 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`.
Audit
Dependencies
eslint-plugin-importrequiredThis package is a resolver specifically designed for use with eslint-plugin-import, providing its module resolution capabilities.
resolverequiredInternally, this resolver leverages the 'resolve' package for its core module resolution logic, and its configuration options are passed directly to 'resolve'.