{"id":12728,"library":"eslint-import-resolver-typescript","title":"ESLint Resolver for TypeScript Imports","description":"This package provides a TypeScript-aware resolver for `eslint-plugin-import` and its faster alternative, `eslint-plugin-import-x`. It enables ESLint to correctly resolve import paths in TypeScript projects, including support for `tsconfig.json`'s `paths` mapping, resolving `.cts`, `.mts`, `.ts`, `.tsx`, `.d.cts`, `.d.mts`, and `.d.ts` extensions. A key feature is its preference for `@types/*` definitions or local `.d.ts` files over plain JavaScript files in `node_modules` for versions 2.0.0 and above. The package is actively maintained, with the current stable version being 4.4.4, receiving frequent patch updates and minor feature releases. It supports multiple `tsconfig.json` files and `package.json` `imports`/`exports` fields, ensuring robust module resolution within complex TypeScript setups.","status":"active","version":"4.4.4","language":"javascript","source_language":"en","source_url":"https://github.com/import-js/eslint-import-resolver-typescript","tags":["javascript","typescript","eslint","import","resolver","plugin"],"install":[{"cmd":"npm install eslint-import-resolver-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add eslint-import-resolver-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add eslint-import-resolver-typescript","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for ESLint to function as a linter.","package":"eslint","optional":false},{"reason":"Primary peer dependency; this resolver enhances its module resolution capabilities for TypeScript.","package":"eslint-plugin-import","optional":true},{"reason":"Alternative peer dependency; this resolver enhances its module resolution capabilities for TypeScript.","package":"eslint-plugin-import-x","optional":true}],"imports":[{"note":"When using ESLint's flat configuration (`eslint.config.js`), the resolver module is imported directly as an ES module and then assigned to the 'typescript' key in the `import/resolver` settings. Ensure your config file is an ES module.","wrong":"const tsResolver = require('eslint-import-resolver-typescript');","symbol":"TypeScript Resolver (ESLint Flat Config)","correct":"import tsResolver from 'eslint-import-resolver-typescript';"},{"note":"For traditional `.eslintrc` configurations (JSON, YAML, or CommonJS), the resolver is specified by its package name as a key under `settings['import/resolver']`. A boolean `true` value or an options object is used; ESLint handles the underlying CommonJS `require` automatically. Directly providing the package name as a string value is incorrect.","wrong":"{ 'import/resolver': { 'typescript': 'eslint-import-resolver-typescript' } }","symbol":"TypeScript Resolver (Legacy .eslintrc)","correct":"{ 'import/resolver': { 'typescript': true } }"},{"note":"Options for the resolver can be passed as an object instead of `true`. The `project` option is commonly used to specify the path to your TypeScript configuration file(s) for advanced resolution scenarios.","symbol":"TypeScript Resolver with Options","correct":"{ 'import/resolver': { 'typescript': { 'alwaysTryTypes': true, 'project': './tsconfig.eslint.json' } } }"}],"quickstart":{"code":"/* eslint.config.js */\nimport eslintPluginImport from 'eslint-plugin-import';\nimport tsResolver from 'eslint-import-resolver-typescript';\n\nexport default [\n  {\n    files: ['**/*.ts', '**/*.tsx', '**/*.mts', '**/*.cts'],\n    // Enable import plugin and set up resolver for TypeScript files\n    plugins: {\n      import: eslintPluginImport,\n    },\n    settings: {\n      'import/resolver': {\n        typescript: tsResolver, // Use the imported resolver module\n        node: {\n          extensions: ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.mts', '.cjs', '.cts', '.d.ts'],\n        },\n      },\n      'import/parsers': {\n        '@typescript-eslint/parser': ['.ts', '.tsx', '.mts', '.cts'],\n      },\n    },\n    rules: {\n      'import/no-unresolved': 'error', // Ensure module paths resolve correctly\n      'import/named': 'error',\n      'import/default': 'error',\n      'import/namespace': 'error',\n      'import/order': ['error', { 'newlines-between': 'always' }],\n      // Add other import rules as needed\n    },\n  },\n  // Add configuration for JavaScript files if necessary\n  {\n    files: ['**/*.js', '**/*.jsx', '**/*.mjs', '**/*.cjs'],\n    plugins: {\n      import: eslintPluginImport,\n    },\n    settings: {\n      'import/resolver': {\n        node: {\n          extensions: ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.mts', '.cjs', '.cts', '.d.ts'],\n        },\n      },\n    },\n    rules: {\n      'import/no-unresolved': 'error',\n    },\n  },\n];\n\n/* tsconfig.json (example, typically in project root) */\n{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"lib\": [\"ES2020\", \"DOM\"],\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true,\n    \"forceConsistentCasingInFileNames\": true,\n    \"moduleResolution\": \"Bundler\",\n    \"baseUrl\": \".\", // Required for path mapping\n    \"paths\": {\n      \"@components/*\": [\"./src/components/*\"],\n      \"@utils/*\": [\"./src/utils/*\"]\n    }\n  },\n  \"include\": [\"src/**/*.ts\", \"src/**/*.tsx\"]\n}\n\n// Example usage in src/app.ts (assuming a component 'Button' and util 'formatDate')\n// import { Button } from '@components/button';\n// import { formatDate } from '@utils/date';\n","lang":"typescript","description":"Demonstrates setting up `eslint-import-resolver-typescript` within ESLint's modern flat configuration to resolve TypeScript module paths, including `tsconfig.json` `paths` mappings, and proper handling of various module extensions. It also illustrates how to configure specific parsers for different file types."},"warnings":[{"fix":"If unexpected resolution issues arise, particularly with `node_modules` packages, verify your `tsconfig.json` settings and ensure that the correct type definitions are being picked up. You might need to adjust your `compilerOptions.moduleResolution` or `typeRoots`.","message":"Since version 2.0.0, this resolver prioritizes `.d.ts` (TypeScript declaration) files over regular `.js`/`.jsx` files when resolving modules from `node_modules`. This change was implemented to favor `@types/*` definitions or module-internal type declarations, which might alter resolution behavior for some packages where a `.js` file might have been preferred previously.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Before reporting an issue related to `import/default` or `import/named`, consult `eslint-plugin-import`'s documentation or its issue tracker (e.g., `import-js/eslint-plugin-import#1525`) as the problem often resides there. Ensure you're using compatible versions of `eslint-plugin-import` and this resolver.","message":"Problems reported by `eslint-plugin-import` rules like `import/default` or `import/named` are frequently issues with the `eslint-plugin-import` core logic itself, or its interaction with specific module patterns, rather than a bug in this resolver. The resolver's primary role is to provide correct file paths based on TypeScript configuration; type-checking or detailed symbol resolution within files is handled by `eslint-plugin-import` after resolution.","severity":"gotcha","affected_versions":"All versions"},{"fix":"To ensure TypeScript-specific resolutions are prioritized, place `typescript` before `node` or other generic resolvers in your `settings['import/resolver']` object within your ESLint configuration.","message":"When combining `eslint-import-resolver-typescript` with other resolvers (e.g., `eslint-import-resolver-node`) in your ESLint configuration, the order of resolvers matters significantly. If a more generic resolver matches a path before the TypeScript resolver has a chance, the TypeScript-specific resolution logic (like `paths` mapping) might not be applied.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify that `eslint-import-resolver-typescript` is correctly enabled in your ESLint configuration (`settings['import/resolver'].typescript`). Ensure your `tsconfig.json` file is present in a standard location (e.g., project root) or explicitly specified via the `project` option for the resolver.","cause":"TypeScript `paths` mapping in `tsconfig.json` is not being correctly picked up, or the resolver is not configured properly in ESLint.","error":"ESLint: import/no-unresolved: Unable to resolve path to module '@components/button'."},{"fix":"Install `@typescript-eslint/parser` and configure it in your ESLint rules, specifically for `.ts`, `.tsx`, `.mts`, and `.cts` files. Ensure `parserOptions.sourceType: 'module'` is explicitly set for these files in your `eslint.config.js` or `.eslintrc`.","cause":"ESLint is attempting to parse a TypeScript or ES module file using a parser that expects CommonJS, or without the correct `sourceType` configured.","error":"ESLint: Parsing error: 'import' and 'export' may only appear with 'sourceType: \"module\"'."},{"fix":"Ensure `typescript` is installed in your project (`npm install typescript`) and that your `tsconfig.json` file is valid and accessible from where ESLint is run. If you use the `project` option for the resolver, confirm the specified path(s) are correct and resolve to valid `tsconfig.json` files.","cause":"This error often indicates that the TypeScript language service could not be correctly initialized, possibly due to an invalid or inaccessible `tsconfig.json` path, or a missing `typescript` dependency.","error":"TypeError: Cannot read properties of undefined (reading 'getProgram') or similar errors related to TypeScript program initialization."}],"ecosystem":"npm"}