repository·master·Indexed 23 days ago
https://github.com/aleclarson/vite-tsconfig-pathsA Vite plugin that enables path aliasing by reading and applying the `paths` configuration from `tsconfig.json` files. It supports custom project discovery strategies (eager or lazy), root directory specification, and path resolution for non-TypeScript modules via the `loose` option or `allowJs` setting. Version 7.0.0-alpha.1.
The plugin respects standard TypeScript configuration options:
allowJs: When true, path resolution extends to .astro, .vue, .svelte, .mdx, .mjs, .js, and .jsx files.baseUrl: If defined, it is prepended to all bare imports and takes precedence over node_modules, matching TypeScript's behavior.include/exclude: These glob patterns are respected using a lightweight glob-to-regex compiler.By default, the plugin only resolves imports for TypeScript and JavaScript files. To enable path resolution for other file types (e.g., .vue, .svelte, .mdx), you have two options:
Option 1: Update tsconfig.json
Set allowJs to true in your tsconfig.json:
{
"compilerOptions": {
"allowJs": true
}
}Option 2: Use the loose plugin option
Pass loose: true to the tsconfigPaths constructor in your Vite config. This is useful if you want to avoid modifying your tsconfig.json or if allowJs does not resolve the issue.
You can install vite-tsconfig-paths using pnpm, npm, or yarn as a development dependency.
pnpm add -D vite-tsconfig-paths
# or
npm install --save-dev vite-tsconfig-paths
# or
yarn add -D vite-tsconfig-pathspnpm add -D vite-tsconfig-pathsTo use the plugin, follow these steps:
"type": "module" in package.json, or rename your Vite config to vite.config.mjs or vite.config.mts.tsconfigPaths() to your plugins array in vite.config.ts.Note: CSS imports are not supported due to Vite limitations.
import { defineConfig } from 'vite'
import tsconfigPaths from 'vite-tsconfig-paths'
export default defineConfig({
plugins: [tsconfigPaths()],
})The plugin uses two strategies for finding and parsing tsconfig.json files via the projectDiscovery option:
'eager')tsconfig.json files are loaded and parsed immediately when the plugin initializes.'lazy')tsconfig.json files are parsed only when an import is encountered in a module that exists within the directory (or a subdirectory) of a discovered tsconfig.json.projects option alongside 'lazy' to ensure project references are correctly discovered.'lazy' if your tsconfig.json files use ../* paths in their include or files arrays, as the plugin may fail to discover the config file.If path resolution is not working as expected, you can use the following methods to debug:
DEBUG variable set to see output:DEBUG=vite-tsconfig-paths yarn vitelogFile: true in the plugin configuration. This writes a full resolution trace to vite-tsconfig-paths.log in your working directory.The tsconfigPaths plugin accepts several options to customize behavior. It is recommended to start without options and only add them as needed.
| Option | Type | Description |
|---|---|---|
projectDiscovery | "eager" | "lazy" | Controls how tsconfigs are loaded. Default is "eager". In "lazy" mode, files are only scanned when an import is encountered in a supported module. |
root | string | The directory to search for tsconfig.json files. |
projects | string[] | Explicit paths to tsconfig files (relative to root). Use root instead if possible. |
loose | boolean | If true, any file transpiled to JS will have its imports resolved. Disables strictness for TS/JS importers. |
importerFilter | (importer: string) => boolean | A function to filter which files have their imports resolved. Has no effect if loose is true. |
parseNative | boolean | Uses tsconfck.parseNative to delegate loading to the TypeScript compiler. Warning: Can slow startup by ~600ms. |
ignoreConfigErrors | boolean | If true, parsing errors in tsconfig files are ignored. Useful for monorepos. |
logFile | string | boolean | Enables detailed resolution logs. Pass true for vite-tsconfig-paths.log in the working directory, or provide a custom path. |
skip | (dir: string) => boolean | A function to determine which directories to skip during search (e.g., to improve performance in large monorepos). |
import { defineConfig } from 'vite'
import tsconfigPaths from 'vite-tsconfig-paths'
export default defineConfig({
plugins: [
tsconfigPaths({
/* options go here */
}),
],
})The vite-tsconfig-paths plugin allows Vite to resolve module imports using the paths configuration defined in your tsconfig.json.
To use it, import the default export from vite-tsconfig-paths and add it to your vite.config.ts plugins array. You can optionally pass a PluginOptions object to configure its behavior.
The plugin accepts an optional PluginOptions object. Key configuration capabilities include:
root: Specifies a custom project root relative to the Vite config root.logFile: Enables logging.true to log to a default file named vite-tsconfig-paths.log.string to specify a custom log file path.skip: A function used to skip specific directories during resolution. By default, .git and node_modules are skipped. You can provide a custom function (dir: string) => boolean to extend this behavior.