{"id":12782,"library":"vite-tsconfig-paths","title":"Vite TypeScript Path Resolver","description":"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.","status":"active","version":"6.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/aleclarson/vite-tsconfig-paths","tags":["javascript","vite","resolver","tsconfig","paths","typescript"],"install":[{"cmd":"npm install vite-tsconfig-paths","lang":"bash","label":"npm"},{"cmd":"yarn add vite-tsconfig-paths","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-tsconfig-paths","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency as it's a Vite plugin.","package":"vite","optional":false}],"imports":[{"note":"The primary plugin function is a named export. Attempting to use a default import will result in a TypeError.","wrong":"import viteTsconfigPaths from 'vite-tsconfig-paths'","symbol":"viteTsconfigPaths","correct":"import { viteTsconfigPaths } from 'vite-tsconfig-paths'"},{"note":"While not directly from 'vite-tsconfig-paths', this type is essential for configuring Vite plugins in TypeScript.","symbol":"UserConfig","correct":"import type { UserConfig } from 'vite'"},{"note":"Again, not directly from this package, but useful for type-hinting plugin arrays in Vite configs.","symbol":"Plugin","correct":"import type { Plugin } from 'vite'"}],"quickstart":{"code":"import { defineConfig } from 'vite';\nimport { viteTsconfigPaths } from 'vite-tsconfig-paths';\n\nexport default defineConfig({\n  plugins: [viteTsconfigPaths({\n    // Optional: Specify configuration file names (defaults to ['tsconfig.json', 'jsconfig.json'])\n    configNames: ['tsconfig.json'],\n    // Optional: 'eager' (default) or 'lazy'. 'lazy' loads tsconfig on demand.\n    projectDiscovery: 'eager',\n    // Optional: Enable logging of resolution traces to a file.\n    // logFile: true \n  })],\n});\n\n// Example tsconfig.json structure that this plugin resolves:\n/*\n{\n  \"compilerOptions\": {\n    \"baseUrl\": \".\",\n    \"paths\": {\n      \"@components/*\": [\"src/components/*\"],\n      \"@utils/*\": [\"src/utils/*\"]\n    }\n  },\n  \"include\": [\"src\"]\n}\n*/","lang":"typescript","description":"Demonstrates how to install `vite-tsconfig-paths` and integrate it into `vite.config.ts`, enabling TypeScript path alias resolution."},"warnings":[{"fix":"Refer to the v7 migration guide upon its stable release for updated configuration and potential API changes.","message":"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.","severity":"breaking","affected_versions":">=7.0.0-alpha.1"},{"fix":"Test your build and development environment thoroughly after upgrading to v6. If issues arise, consider downgrading to v5 and reporting the problem.","message":"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.","severity":"breaking","affected_versions":">=6.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<6.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<5.1.2, <6.0.0-beta.4"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=6.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"Error: [vite-tsconfig-paths] No tsconfig.json found."},{"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.","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.","error":"Module not found: Can't resolve '~/components/Button'"},{"fix":"Change your import statement from `import viteTsconfigPaths from 'vite-tsconfig-paths'` to `import { viteTsconfigPaths } from 'vite-tsconfig-paths'`.","cause":"This error typically occurs when attempting to import `viteTsconfigPaths` as a default import, but it is provided as a named export.","error":"TypeError: (0 , vite_tsconfig_paths_1.default) is not a function"}],"ecosystem":"npm"}