eslint-import-resolver-typescript

Add the resolver to your .eslintrc configuration under settings.import/resolver.typescript. This allows ESLint to resolve TypeScript files and respect tsconfig.json paths.

{
  "plugins": ["import"],
  "rules": {
    "import/no-unresolved": "error"
  },
  "settings": {
    "import/parsers": {
      "@typescript-eslint/parser": [".ts", ".tsx"]
    },
    "import/resolver": {
      "typescript": {
        "alwaysTryTypes": true,
        "bun": true,
        "project": "path/to/folder"
      }
    }
  }
}

Install the resolver along with your preferred ESLint import plugin.

For eslint-plugin-import-x (recommended for speed):

# npm
npm i -D eslint-plugin-import-x eslint-import-resolver-typescript

# pnpm
pnpm i -D eslint-plugin-import-x eslint-import-resolver-typescript

# yarn
yarn add -D eslint-plugin-import-x eslint-import-resolver-typescript

# bun
bun add -d eslint-plugin-import-x eslint-import-resolver-typescript

For eslint-plugin-import:

# npm
npm i -D eslint-plugin-import eslint-import-resolver-typescript

# pnpm
pnpm i -D eslint-plugin-import eslint-import-resolver-typescript

# yarn
yarn add -D eslint-plugin-import eslint-import-resolver-typescript

# bun
bun add -d eslint-plugin-import eslint-import-resolver-typescript

If you are using eslint-plugin-import-x@>=4.5.0, you can use createTypeScriptImportResolver to reference the resolver directly in your ESLint flat config.

For older versions of eslint-plugin-import-x or when using eslint-plugin-import, use the import/resolver key in the settings object instead.

// For eslint-plugin-import-x@>=4.5.0
import { createTypeScriptImportResolver } from 'eslint-import-resolver-typescript'

export default [
  {
    settings: {
      'import-x/resolver-next': [
        createTypeScriptImportResolver({
          alwaysTryTypes: true,
          bun: true,
          project: 'path/to/folder',
        }),
      ],
    },
  },
]

Bun provides built-in modules like bun:test that are not resolved by default. To enable resolution for these modules, use one of the following methods:

1. Set the bun: true option in your resolver configuration.
2. Run ESLint using the Bun runtime: bun --bun eslint.
3. Configure run.bun in your bunfig.toml to automatically alias node to bun.

// In your config
{
  "typescript": {
    "bun": true
  }
}

The project option tells the resolver which tsconfig.json or jsconfig.json files to use for module resolution. This is essential for supporting paths mapping.

Supported formats:

• A single path to a folder: 'path/to/folder'
• A glob pattern: 'packages/*/{ts,js}config.json'
• An array of specific paths: ['packages/module-a/tsconfig.json', 'packages/module-b/jsconfig.json']
• An array of glob patterns: ['packages/*/tsconfig.json', 'other-packages/*/jsconfig.json']

project: 'path/to/folder'
// or
project: ['packages/module-a/tsconfig.json', 'packages/module-b/jsconfig.json']

The resolver is configured via TypeScriptResolverOptions. Key behaviors include:

• project: An array of paths to tsconfig.json files. If provided, the resolver will attempt to match the current file to the most appropriate TypeScript project.
• alwaysTryTypes: A boolean (defaults to true) that determines whether the resolver should attempt to find @types/ packages for non-absolute, non-relative imports that fail initial resolution.
• tsconfig: An object allowing fine-grained control over TypeScript configuration, such as setting references: 'auto' or specifying a configFile.
• bun: A boolean to explicitly enable Bun-specific builtin module detection.

Note: The resolver uses normalizeOptions internally to ensure these settings are applied correctly relative to the current working directory.

The resolver accepts options passed through to unrs-resolver.

Key options include:

• alwaysTryTypes: (Boolean) Always try to resolve types under <root>@types directory even if it doesn't contain any source code.
• bun: (Boolean) Resolve Bun modules.
• project: (String | String[] | Glob) Path(s) to tsconfig.json or jsconfig.json.
• conditionNames: (Array) Custom export conditions to check.
• extensions: (Array) File extensions to attempt resolving.
• extensionAlias: (Object) Mapping of extensions to their aliases.
• mainFields: (Array) Fields in package.json to check for module entry points.

To use this resolver with ESLint (specifically with eslint-plugin-import or eslint-plugin-import-x), you should use the createTypeScriptImportResolver factory function. This function returns an object compatible with the ESLint resolver interface, including the interfaceVersion, name, and a resolve method.

When called by ESLint, the resolve method automatically handles context (like cwd) and uses the provided TypeScriptResolverOptions to locate TypeScript modules.

import { createTypeScriptImportResolver } from 'eslint-import-resolver-typescript';

// This is what you would typically configure in your ESLint settings
const resolver = createTypeScriptImportResolver({
  project: ['tsconfig.json'],
  alwaysTryTypes: true
});

The resolve function and the resolver interface return a ResolvedResult object representing the outcome of the module lookup.

{
  found: boolean;
  path?: string | null;
}