ESLint Resolver for TypeScript Imports

Common errors

• ESLint: import/no-unresolved: Unable to resolve path to module '@components/button'.

  cause TypeScript `paths` mapping in `tsconfig.json` is not being correctly picked up, or the resolver is not configured properly in ESLint.
  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.

• ESLint: Parsing error: 'import' and 'export' may only appear with 'sourceType: "module"'.

  cause ESLint is attempting to parse a TypeScript or ES module file using a parser that expects CommonJS, or without the correct `sourceType` configured.
  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`.

• TypeError: Cannot read properties of undefined (reading 'getProgram') or similar errors related to TypeScript program initialization.

  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.
  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.

Warnings

• breaking 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.
  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`.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install eslint-import-resolver-typescript npm
• yarn add eslint-import-resolver-typescript yarn
• pnpm add eslint-import-resolver-typescript pnpm

Imports

• TypeScript Resolver (ESLint Flat Config)
  wrong:

  const tsResolver = require('eslint-import-resolver-typescript');

  correct:

  import tsResolver from 'eslint-import-resolver-typescript';

  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.
• TypeScript Resolver (Legacy .eslintrc)
  wrong:

  { 'import/resolver': { 'typescript': 'eslint-import-resolver-typescript' } }

  correct:

  { 'import/resolver': { 'typescript': true } }

  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.
• TypeScript Resolver with Options

  { 'import/resolver': { 'typescript': { 'alwaysTryTypes': true, 'project': './tsconfig.eslint.json' } } }

  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.

Quickstart

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.

/* eslint.config.js */
import eslintPluginImport from 'eslint-plugin-import';
import tsResolver from 'eslint-import-resolver-typescript';

export default [
  {
    files: ['**/*.ts', '**/*.tsx', '**/*.mts', '**/*.cts'],
    // Enable import plugin and set up resolver for TypeScript files
    plugins: {
      import: eslintPluginImport,
    },
    settings: {
      'import/resolver': {
        typescript: tsResolver, // Use the imported resolver module
        node: {
          extensions: ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.mts', '.cjs', '.cts', '.d.ts'],
        },
      },
      'import/parsers': {
        '@typescript-eslint/parser': ['.ts', '.tsx', '.mts', '.cts'],
      },
    },
    rules: {
      'import/no-unresolved': 'error', // Ensure module paths resolve correctly
      'import/named': 'error',
      'import/default': 'error',
      'import/namespace': 'error',
      'import/order': ['error', { 'newlines-between': 'always' }],
      // Add other import rules as needed
    },
  },
  // Add configuration for JavaScript files if necessary
  {
    files: ['**/*.js', '**/*.jsx', '**/*.mjs', '**/*.cjs'],
    plugins: {
      import: eslintPluginImport,
    },
    settings: {
      'import/resolver': {
        node: {
          extensions: ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.mts', '.cjs', '.cts', '.d.ts'],
        },
      },
    },
    rules: {
      'import/no-unresolved': 'error',
    },
  },
];

/* tsconfig.json (example, typically in project root) */
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "Bundler",
    "baseUrl": ".", // Required for path mapping
    "paths": {
      "@components/*": ["./src/components/*"],
      "@utils/*": ["./src/utils/*"]
    }
  },
  "include": ["src/**/*.ts", "src/**/*.tsx"]
}

// Example usage in src/app.ts (assuming a component 'Button' and util 'formatDate')
// import { Button } from '@components/button';
// import { formatDate } from '@utils/date';