eslint-import-resolver-typescript

eslint-import-resolver-typescript adds TypeScript support to eslint-plugin-import and eslint-plugin-import-x, which otherwise only understand plain JavaScript module resolution. Without it, rules like import/no-unresolved and import/named misfire constantly in a TypeScript codebase because ESLint’s default resolver has no notion of .ts, .tsx, .d.ts extensions, tsconfig.json path mapping, or the imports/exports fields in package.json.

Under the hood it delegates the actual filesystem resolution to unrs-resolver (a Rust-backed resolver also used by other tools in the Rust-JS ecosystem for speed), while it owns the TypeScript-specific policy layer: parsing tsconfig.json/jsconfig.json via get-tsconfig, matching path aliases, preferring @types/* type declarations over sibling .js/.jsx files, and supporting multiple tsconfigs in a monorepo (either as an explicit array, a glob, or TypeScript project references).

Configuration is exposed two ways: as a flat-config resolver object (createTypeScriptImportResolver) for eslint-plugin-import-x@>=4.5, and as the classic import/resolver: { typescript: {...} } settings block for older eslint-plugin-import setups. Both accept the same option surface — alwaysTryTypes, bun (for Bun’s built-in modules), project path(s), plus pass-through options like conditionNames, extensions, and mainFields that map directly onto unrs-resolver’s own resolution algorithm.

It has been a near-default dependency in TypeScript + ESLint projects since 2017, with 45 contributors and a v2/v3/v4 history that tracks changes in how Node and bundlers resolve TypeScript-specific file extensions and export conditions.

What You Get

• Flat-config resolver factory - createTypeScriptImportResolver() for direct use in eslint.config.js with eslint-plugin-import-x >=4.5, no legacy settings block needed
• Classic settings-block support - import/resolver: { typescript: {...} } for .eslintrc and older eslint-plugin-import versions
• tsconfig/jsconfig path mapping - resolves paths aliases from tsconfig.json or jsconfig.json, including glob patterns and arrays for monorepos
• TypeScript project references support - can resolve nested tsconfigs across a monorepo using references, avoiding one-tsconfig-per-package duplication
• @types/* precedence - alwaysTryTypes resolves ambient type declarations over sibling plain JS files, useful for packages with separate @types definitions
• Bun module resolution - bun: true (or running under bun --bun eslint) resolves Bun’s built-in modules like bun:test
• Rust-backed resolution engine - delegates to unrs-resolver for the actual filesystem walk, keeping large-project lint runs fast

Common Use Cases

• Fixing false-positive import/no-unresolved errors - a team adds TypeScript to a JS codebase and ESLint’s import rules start flagging valid .ts imports as unresolved; this resolver fixes that without disabling the rule
• Monorepos with multiple tsconfigs - a pnpm/Yarn workspace with per-package tsconfig.json files configures project: 'packages/*/tsconfig.json' so cross-package imports resolve correctly from any file
• Migrating from .eslintrc to flat config - a project moving to ESLint 9’s flat config switches from the import/resolver settings object to createTypeScriptImportResolver() for a cleaner, importable config
• Projects using path aliases - an app defines @/* path mapping in tsconfig.json for absolute imports; without this resolver ESLint can’t verify those aliased imports actually point to real files
• Bun-based TypeScript projects - a project running on Bun needs ESLint to recognize bun:test and other Bun built-ins as valid imports rather than flagging them as missing modules

Under The Hood

Architecture The package centers on a single resolve() function in src/index.ts that layers TypeScript-specific policy on top of a general-purpose resolver. It first short-circuits Node/Bun core modules via isBuiltin/isBunBuiltin, then normalizes caller options in normalize-options.ts (resolving and sorting candidate tsconfig projects by directory affinity in helpers.ts’s sortProjectsByAffinity), and finally delegates the actual filesystem walk to an unrs-resolver ResolverFactory instance. Three module-level caches (resolverCache, tsconfigCache, matcherCache), keyed by a stable hash of the options plus cwd, avoid re-parsing tsconfig files and rebuilding resolvers across repeated ESLint rule invocations — a meaningful cost given ESLint calls resolvers per-import, per-file. The design cleanly separates “which tsconfig applies to this file” (this package’s job) from “how do we actually resolve a module path” (delegated entirely to unrs-resolver), so a change to Node’s module resolution algorithm is absorbed by the dependency rather than requiring changes here.

Tech Stack Written in TypeScript, built dual-format (ESM lib/index.js + CJS lib/index.cjs) via tsc and tsdown, and published under the import-js GitHub org. Core runtime dependencies are narrow and purpose-built: unrs-resolver (Rust-backed resolution), get-tsconfig (tsconfig/jsconfig parsing and path-matcher creation), is-bun-module, stable-hash-x for cache keys, and tinyglobby for glob-pattern project globbing. It integrates with ESLint via the eslint-import-context package’s useRuleContext() rather than depending on ESLint directly, letting it work across both eslint-plugin-import and eslint-plugin-import-x. Yarn Berry (PnP-aware, packageManager: yarn@4.9.2) manages the workspace, with changesets driving releases.

Code Quality Tests run under Vitest (vitest run) plus a standalone e2e smoke test (tests/e2e/withJsExtension/test.cjs), with an extensive tests/e2e/ suite covering path-alias resolution, multiple tsconfigs, tsconfig project references, dotted include/exclude paths, and querystring-suffixed imports — each as its own fixture directory with a real tsconfig and expected resolution snapshot. The project enforces a 100%-minimum type-coverage threshold via the type-coverage tool (typeCoverage.atLeast: 100 in package.json), which is a stronger and more unusual guarantee than typical --noImplicitAny type checking. Linting runs through the shared @1stg/common-config ESLint config plus a dedicated tsc --noEmit pass, and CI (GitHub Actions) enforces both on every PR alongside Codecov coverage reporting. No test framework gaps were found; the codebase is small and every exported function has corresponding fixture coverage.

API Design The public surface is deliberately narrow: one resolver factory (createTypeScriptImportResolver) for flat config, and one options object shape shared with the legacy import/resolver.typescript settings block, so migrating between ESLint config formats requires no relearning. Defaults are sensible and documented inline in the README (default extensions, extensionAlias, conditionNames, mainFields are all shown as copy-pasteable JSON), which keeps the common case a one-line alwaysTryTypes: true addition to config while still exposing every knob unrs-resolver itself supports for advanced monorepo or non-standard resolution setups.