vite-tsconfig-paths

vite-tsconfig-paths is a Vite plugin that teaches Vite’s module resolver to understand the path aliases already defined in a project’s tsconfig.json or jsconfig.json compilerOptions.paths, so aliased imports like @/components/Button resolve correctly without duplicating the mapping in vite.config.ts. It supports monorepos and TypeScript project references by crawling for tsconfig files, or accepting an explicit list via the projects option, and as of v6 it watches tsconfig files for changes so edits take effect without restarting the dev server.

The plugin ships both eager and lazy discovery strategies, letting large workspaces skip scanning the entire tree for tsconfig files up front. As of v7 it delegates resolution to oxc-resolver instead of loading the TypeScript compiler, avoiding TypeScript version conflicts. It deliberately does not resolve CSS imports (a Vite resolver limitation) and requires allowJs, or the loose option, for path resolution inside non-TypeScript files such as .vue or .svelte templates.

What You Get

• Automatic resolution of tsconfig.json/jsconfig.json path aliases inside Vite, with no duplicate alias config in vite.config.ts
• Monorepo-aware project discovery, including TypeScript project references via the extends and references fields
• Eager or lazy tsconfig discovery strategies, plus file watching so edited tsconfig paths apply without restarting the dev server
• An oxc-resolver-backed resolution engine (v6+/v7) that avoids loading the TypeScript compiler just to read compilerOptions.paths

Common Use Cases

• Migrating a create-react-app or webpack project to Vite while keeping existing @/ or ~/ import aliases intact
• Working in a pnpm/Turborepo monorepo where each package has its own tsconfig.json and path mappings
• Resolving imports in Vue, Svelte, or MDX files that reference TypeScript path aliases, with allowJs or loose mode enabled
• Debugging why an aliased import isn’t resolving, using the DEBUG=vite-tsconfig-paths flag or the logFile option’s resolution trace

Under The Hood

Architecture

The plugin is a single Vite plugin object (src/index.ts) with enforce: 'pre' that hooks configResolved, configureServer, buildStart, and a filtered resolveId. On configResolved it builds a TsconfigResolvers instance (src/resolver.ts) that maintains a directory cache keyed by importer path, a WeakMap of parsed Projects to compiled Resolver functions, and a generation counter used to invalidate the cache when tsconfig files are edited. resolveId’s hook filter (id: /^(?!\.\.|\.\/|\0)/) skips relative and virtual-module imports at the native Rolldown/Rollup layer where supported, falling back to manual checks for older Vite/Rollup versions. src/config.ts recursively walks the workspace (bounded by a small inlined promise-concurrency limiter to avoid exhausting file descriptors in large monorepos) and follows a tsconfig’s references field to build a full project graph via get-tsconfig’s readTsconfig.

Tech Stack

Written in TypeScript, built with Rolldown (rolldown.config.ts) and a custom .d.ts generation script, formatted/linted with oxfmt and oxlint rather than Prettier/ESLint. Runtime dependencies are minimal and deliberate: get-tsconfig for parsing tsconfig files (including extends chains), oxc-resolver for the actual module resolution engine as of v6/v7, and debug for its DEBUG=vite-tsconfig-paths tracing convention. vite itself is a peer dependency (>=5.0.0), and the package targets Node >=20.20 for v7. Tests run under Vitest, with execa used to shell out to a real tsc binary for cross-validation against TypeScript’s own resolution.

Code Quality

The test suite (730 lines across test/config.test.ts, test/plugin.test.ts, test/resolver.test.ts) is fixture-driven: plugin.test.ts iterates every directory under test/__fixtures__ and asserts that both a real tsc --noEmit-style invocation and an actual Vite build succeed for that fixture, giving strong confidence that path resolution matches TypeScript’s own behavior rather than a reimplementation of it. Error handling is explicit and user-facing — resolver.ts surfaces malformed tsconfig parse errors through Vite’s logger with an actionable message about the ignoreConfigErrors option, rather than swallowing them. The codebase is fully typed, uses oxlint (a stricter, faster ESLint alternative) for static analysis, and CI is configured under .github/.

What Makes It Unique

Rather than reimplementing TypeScript’s path-mapping semantics from scratch, later versions of the plugin lean on oxc-resolver, a Rust-based resolver shared with the broader oxc tooling ecosystem, specifically to avoid needing the TypeScript compiler as a peer dependency — a deliberate design choice called out in the README to unblock projects experimenting with TypeScript 7’s rewritten (non-npm-typescript) toolchain. Its lazy discovery mode, which only parses a directory’s tsconfig when an import from that directory is actually seen, is a comprehensive answer to a real scaling problem in large monorepos, one that many comparable resolver plugins address only partially or not at all.