Vite TypeScript Path Resolver

6.1.1 · active · verified Sun Apr 19

vite-tsconfig-paths is a Vite plugin designed to automatically resolve TypeScript `compilerOptions.paths` aliases within a Vite project. It simplifies development by allowing developers to use absolute or aliased paths defined in their `tsconfig.json` (or `jsconfig.json`) without requiring additional manual configuration in Vite's resolver. The current stable version is 6.1.1, with an active development branch leading to v7.0.0-alpha.1, which introduces a significant architectural shift towards the OXC and Rolldown ecosystem for enhanced performance and a reduced dependency footprint. The plugin offers features like on-demand `tsconfig` discovery, automatic watching and reloading of `tsconfig` files, and fine-grained control over resolution via options such as `importerFilter`. Its primary differentiator is its robust and performant solution for directly integrating with and resolving `tsconfig.paths` in Vite.

Common errors

```
Error: [vite-tsconfig-paths] No tsconfig.json found.
```
cause The plugin could not locate a `tsconfig.json` or `jsconfig.json` file in the project root or parent directories, or the `configNames` option is incorrect.

fix Ensure a `tsconfig.json` (or `jsconfig.json`) exists in your project's root or a relevant subdirectory. Verify the `configNames` option if you are using non-standard file names.
```
Module not found: Can't resolve '~/components/Button'
```
cause The path alias defined in `tsconfig.paths` is not being correctly resolved by Vite, potentially due to incorrect plugin configuration or an issue with the `tsconfig.json` itself.

fix Double-check your `tsconfig.json` `baseUrl` and `paths` configuration. Ensure `viteTsconfigPaths` is correctly added to your `vite.config.ts` plugins array and that the path exists on the filesystem.
```
TypeError: (0 , vite_tsconfig_paths_1.default) is not a function
```
cause This error typically occurs when attempting to import `viteTsconfigPaths` as a default import, but it is provided as a named export.

fix Change your import statement from `import viteTsconfigPaths from 'vite-tsconfig-paths'` to `import { viteTsconfigPaths } from 'vite-tsconfig-paths'`.

Warnings

breaking Version 7.0.0-alpha.1 introduces a significant architectural overhaul, replacing custom path-matching with `oxc-resolver` and adding Rolldown readiness. While in alpha, users planning to upgrade from v6 to v7 stable should expect breaking changes and thoroughly review migration guides.
Fix: Refer to the v7 migration guide upon its stable release for updated configuration and potential API changes.
breaking Version 6.0.0 involved 'extensive internal refactoring' despite the release note stating 'No intentional breaking changes'. Users migrating from v5 to v6 should exercise caution and perform thorough testing, as unintended behavioral changes or edge-case regressions might occur.
Fix: Test your build and development environment thoroughly after upgrading to v6. If issues arise, consider downgrading to v5 and reporting the problem.
gotcha Prior to v6.1.0, the plugin might incorrectly resolve paths to `.d.ts` files, leading to unexpected type overrides or resolution issues. Additionally, fine-grained control over which files are resolved by the plugin was limited.
Fix: Upgrade to v6.1.0 or newer to benefit from the `importerFilter` option and the fix that ignores resolutions pointing to `.d.ts` files.
gotcha On Windows systems, older versions (specifically pre-v5.1.2 and some v6.0.0-beta versions) had issues with drive letter capitalization in paths, leading to incorrect resolutions or 'file not found' errors.
Fix: Ensure you are using `vite-tsconfig-paths` v6.0.0-beta.4 or newer, or v5.1.2 to avoid known Windows path resolution regressions.
gotcha The `projectDiscovery` option introduced in v6 (defaulting to 'eager') can affect performance and how `tsconfig` files are loaded. In complex monorepos, 'lazy' discovery might be more suitable but requires careful configuration, especially with project references.
Fix: Review the `projectDiscovery` option. For large projects or monorepos, consider setting `projectDiscovery: 'lazy'` and explicitly listing main projects in the `projects` array option if using TypeScript project references.

Install

npm install vite-tsconfig-paths npm
yarn add vite-tsconfig-paths yarn
pnpm add vite-tsconfig-paths pnpm

Imports

viteTsconfigPaths
wrong:
```
import viteTsconfigPaths from 'vite-tsconfig-paths'
```
correct:
```
import { viteTsconfigPaths } from 'vite-tsconfig-paths'
```
The primary plugin function is a named export. Attempting to use a default import will result in a TypeError.
UserConfig
```
import type { UserConfig } from 'vite'
```
While not directly from 'vite-tsconfig-paths', this type is essential for configuring Vite plugins in TypeScript.
Plugin
```
import type { Plugin } from 'vite'
```
Again, not directly from this package, but useful for type-hinting plugin arrays in Vite configs.

Quickstart

Demonstrates how to install `vite-tsconfig-paths` and integrate it into `vite.config.ts`, enabling TypeScript path alias resolution.

import { defineConfig } from 'vite';
import { viteTsconfigPaths } from 'vite-tsconfig-paths';

export default defineConfig({
  plugins: [viteTsconfigPaths({
    // Optional: Specify configuration file names (defaults to ['tsconfig.json', 'jsconfig.json'])
    configNames: ['tsconfig.json'],
    // Optional: 'eager' (default) or 'lazy'. 'lazy' loads tsconfig on demand.
    projectDiscovery: 'eager',
    // Optional: Enable logging of resolution traces to a file.
    // logFile: true 
  })],
});

// Example tsconfig.json structure that this plugin resolves:
/*
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  },
  "include": ["src"]
}
*/

view raw JSON →