Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
viteTsconfigPaths
✓ import { viteTsconfigPaths } from 'vite-tsconfig-paths'
✗ 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.
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"]
}
*/
Debug
Known issues
breakingVersion 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.fixRefer to the v7 migration guide upon its stable release for updated configuration and potential API changes.
affects: >=7.0.0-alpha.1
breakingVersion 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.fixTest your build and development environment thoroughly after upgrading to v6. If issues arise, consider downgrading to v5 and reporting the problem.
affects: >=6.0.0
gotchaPrior 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.fixUpgrade to v6.1.0 or newer to benefit from the `importerFilter` option and the fix that ignores resolutions pointing to `.d.ts` files.
affects: <6.1.0
gotchaOn 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.fixEnsure you are using `vite-tsconfig-paths` v6.0.0-beta.4 or newer, or v5.1.2 to avoid known Windows path resolution regressions.
affects: <5.1.2, <6.0.0-beta.4
gotchaThe `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.fixReview 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.
affects: >=6.0.0
Errors
Common errors & fixes
Error: [vite-tsconfig-paths] No tsconfig.json found.
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.
fixEnsure 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'
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.
fixDouble-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
This error typically occurs when attempting to import `viteTsconfigPaths` as a default import, but it is provided as a named export.
fixChange your import statement from `import viteTsconfigPaths from 'vite-tsconfig-paths'` to `import { viteTsconfigPaths } from 'vite-tsconfig-paths'`. Audit
Dependencies
viterequiredPeer dependency as it's a Vite plugin.