0
# vite-tsconfig-paths
1

2
Vite plugin enabling TypeScript path mapping from tsconfig.json. Resolves path aliases and baseUrl, eliminating relative path imports.
3

4
**Installation**: `npm install --save-dev vite-tsconfig-paths`
5

6
## Core API
7

8
### Import
9

10
```typescript
11
import tsconfigPaths from 'vite-tsconfig-paths';
12
import type { PluginOptions } from 'vite-tsconfig-paths';
13
```
14

15
### Plugin Factory
16

17
```typescript { .api }
18
/**
19
 * Creates Vite plugin for TypeScript path resolution
20
 * @param opts - Configuration options
21
 * @returns Vite Plugin (name: 'vite-tsconfig-paths', enforce: 'pre')
22
 */
23
function default(opts?: PluginOptions): Plugin;
24
```
25

26
### Configuration Interface
27

28
```typescript { .api }
29
interface PluginOptions {
30
  /**
31
   * Directory to crawl for tsconfig.json files
32
   * Default: viteConfig.root (with projects) or searchForWorkspaceRoot(viteConfig.root)
33
   */
34
  root?: string;
35

36
  /**
37
   * Explicit tsconfig.json paths (disables auto-crawl)
38
   * Absolute or relative to root
39
   */
40
  projects?: string[];
41

42
  /**
43
   * Enable path resolution for non-TS/JS files (.vue, .svelte, .mdx)
44
   * Use when allowJs insufficient
45
   */
46
  loose?: boolean;
47

48
  /**
49
   * Use TypeScript compiler for parsing (adds ~600ms startup)
50
   * Only for non-standard tsconfig
51
   */
52
  parseNative?: boolean;
53

54
  /**
55
   * Suppress tsconfig.json error warnings
56
   * Useful in monorepos
57
   */
58
  ignoreConfigErrors?: boolean;
59

60
  /**
61
   * Config file names to search
62
   * Default: ["tsconfig.json", "jsconfig.json"]
63
   */
64
  configNames?: string[];
65

66
  /**
67
   * Directory skip predicate (.git, node_modules always skipped)
68
   * Returns true to skip
69
   */
70
  skip?: (dir: string) => boolean;
71
}
72
```
73

74
### TypeScript Config Schema
75

76
```typescript { .api }
77
interface TSConfig {
78
  include?: string[];
79
  exclude?: string[];
80
  compilerOptions?: {
81
    baseUrl?: string;
82
    paths?: { [path: string]: string[] };
83
    allowJs?: boolean;
84
    checkJs?: boolean;
85
    outDir?: string;
86
  };
87
}
88
```
89

90
## Usage Patterns
91

92
### Basic Setup
93

94
```typescript
95
import { defineConfig } from 'vite';
96
import tsconfigPaths from 'vite-tsconfig-paths';
97

98
export default defineConfig({
99
  plugins: [tsconfigPaths()],
100
});
101
```
102

103
### Monorepo (Auto-Discovery)
104

105
```typescript
106
export default defineConfig({
107
  plugins: [
108
    tsconfigPaths({
109
      root: '../../', // Workspace root
110
    }),
111
  ],
112
});
113
```
114

115
### Monorepo (Explicit Projects)
116

117
```typescript
118
export default defineConfig({
119
  plugins: [
120
    tsconfigPaths({
121
      root: '.',
122
      projects: [
123
        './packages/app/tsconfig.json',
124
        './packages/shared/tsconfig.json',
125
      ],
126
    }),
127
  ],
128
});
129
```
130

131
### Vue/Svelte (Loose Mode)
132

133
```typescript
134
import vue from '@vitejs/plugin-vue';
135
// or: import { svelte } from '@sveltejs/vite-plugin-svelte';
136

137
export default defineConfig({
138
  plugins: [
139
    vue(), // or svelte()
140
    tsconfigPaths({ loose: true }),
141
  ],
142
});
143
```
144

145
### Custom Directory Skipping
146

147
```typescript
148
export default defineConfig({
149
  plugins: [
150
    tsconfigPaths({
151
      skip: (dir) => ['test', 'dist', 'build'].includes(dir),
152
    }),
153
  ],
154
});
155
```
156

157
### Ignore Config Errors
158

159
```typescript
160
export default defineConfig({
161
  plugins: [
162
    tsconfigPaths({ ignoreConfigErrors: true }),
163
  ],
164
});
165
```
166

167
## TSConfig Path Mapping
168

169
### Standard Aliases
170

171
```json
172
{
173
  "compilerOptions": {
174
    "baseUrl": "./src",
175
    "paths": {
176
      "@components/*": ["components/*"],
177
      "@utils/*": ["utils/*"],
178
      "@/*": ["*"]
179
    }
180
  }
181
}
182
```
183

184
```typescript
185
// Usage
186
import Button from '@components/Button';
187
import { formatDate } from '@utils/date';
188
import { config } from '@/config';
189
```
190

191
### BaseUrl Only
192

193
```json
194
{
195
  "compilerOptions": {
196
    "baseUrl": "./src"
197
  }
198
}
199
```
200

201
```typescript
202
// import { config } from 'config';
203
// Resolves: ./src/config → node_modules/config (fallback)
204
```
205

206
### Include/Exclude Patterns
207

208
```json
209
{
210
  "include": ["src/**/*"],
211
  "exclude": ["src/**/*.test.ts"]
212
}
213
```
214

215
Path resolution only applies to matching files.
216

217
### AllowJs for Non-TS Files
218

219
```json
220
{
221
  "compilerOptions": {
222
    "allowJs": true,
223
    "baseUrl": "./src",
224
    "paths": { "@/*": ["*"] }
225
  }
226
}
227
```
228

229
Enables resolution for `.vue`, `.svelte`, `.mdx`, `.js`, `.jsx`, `.mjs`. Use `loose: true` option if insufficient.
230

231
### Project References
232

233
```json
234
{
235
  "references": [
236
    { "path": "./packages/core" },
237
    { "path": "./packages/utils" }
238
  ]
239
}
240
```
241

242
Plugin auto-loads and processes referenced projects.
243

244
## Architecture
245

246
The plugin operates through Vite's plugin system with these components:
247

248
- **TSConfig Discovery**: Automatically locates and parses tsconfig.json files in project hierarchy, supporting monorepo structures with multiple configuration files
249
- **Path Mapping Resolution**: Converts TypeScript path mappings into resolved module paths that Vite can understand
250
- **Resolver Integration**: Hooks into Vite's module resolution system at 'pre' enforcement stage to intercept and resolve imports
251
- **Include/Exclude Support**: Respects TypeScript's include/exclude patterns to determine which files use path resolution
252
- **Caching Layer**: Maintains resolution caches for performance optimization during development
253

254
## Debug Mode
255

256
Enable debug logging using the `DEBUG` environment variable:
257

258
```bash
259
DEBUG=vite-tsconfig-paths vite              # General logging
260
DEBUG=vite-tsconfig-paths:resolve vite      # Resolution details
261
DEBUG=vite-tsconfig-paths* vite             # All debug output
262
```
263

264
Debug output includes:
265
- TSConfig file discovery and loading
266
- Path mapping compilation
267
- Module resolution attempts
268
- Include/exclude pattern matching
269
- Configuration options
270

271
## Common Use Cases
272

273
### Standard TypeScript Project
274

275
```typescript
276
// vite.config.ts
277
import { defineConfig } from 'vite';
278
import tsconfigPaths from 'vite-tsconfig-paths';
279

280
export default defineConfig({
281
  plugins: [tsconfigPaths()],
282
});
283
```
284

285
```json
286
// tsconfig.json
287
{
288
  "compilerOptions": {
289
    "baseUrl": "./src",
290
    "paths": { "@/*": ["*"] }
291
  }
292
}
293
```
294

295
### Monorepo with Multiple Packages
296

297
```typescript
298
// apps/web/vite.config.ts
299
import { defineConfig } from 'vite';
300
import tsconfigPaths from 'vite-tsconfig-paths';
301

302
export default defineConfig({
303
  plugins: [
304
    tsconfigPaths({
305
      root: '../../', // Auto-discover all tsconfig files in workspace
306
    }),
307
  ],
308
});
309
```
310

311
### Vue 3 Project with Path Aliases
312

313
```typescript
314
// vite.config.ts
315
import { defineConfig } from 'vite';
316
import vue from '@vitejs/plugin-vue';
317
import tsconfigPaths from 'vite-tsconfig-paths';
318

319
export default defineConfig({
320
  plugins: [
321
    vue(),
322
    tsconfigPaths({ loose: true }), // Enable path resolution in .vue files
323
  ],
324
});
325
```
326

327
```json
328
// tsconfig.json
329
{
330
  "compilerOptions": {
331
    "baseUrl": ".",
332
    "paths": {
333
      "@/components/*": ["src/components/*"],
334
      "@/composables/*": ["src/composables/*"],
335
      "@/stores/*": ["src/stores/*"]
336
    },
337
    "allowJs": true
338
  }
339
}
340
```
341

342
### Svelte Project
343

344
```typescript
345
// vite.config.ts
346
import { defineConfig } from 'vite';
347
import { svelte } from '@sveltejs/vite-plugin-svelte';
348
import tsconfigPaths from 'vite-tsconfig-paths';
349

350
export default defineConfig({
351
  plugins: [
352
    svelte(),
353
    tsconfigPaths({ loose: true }), // Enable path resolution in .svelte files
354
  ],
355
});
356
```
357

358
## Troubleshooting
359

360
### Paths Not Resolving
361

362
1. Verify tsconfig.json has `baseUrl` or `paths` defined
363
2. Check file is included in tsconfig's `include` patterns
364
3. Ensure file extension is supported (see allowJs section)
365
4. Enable debug logging: `DEBUG=vite-tsconfig-paths:resolve vite`
366
5. Try `loose: true` option for non-TypeScript files
367

368
### Monorepo Issues
369

370
1. Use `root` option to specify workspace root
371
2. Try `projects` option to explicitly list tsconfig files
372
3. Use `skip` option to exclude large directories (improves performance)
373
4. Enable `ignoreConfigErrors` if some tsconfig files have issues
374

375
### Performance Issues
376

377
1. Use `skip` option to exclude unnecessary directories
378
2. Avoid `parseNative: true` unless absolutely necessary (~600ms startup cost)
379
3. Consider explicit `projects` list instead of auto-discovery in very large monorepos
380

381
### Vite Dev Server Not Updating
382

383
Path mapping changes in tsconfig.json require restarting the Vite dev server. The plugin does not hot-reload configuration changes.
384

385
## Limitations
386

387
- **CSS files**: Due to a Vite limitation, CSS files and CSS dialects cannot be resolved with this plugin
388
- **Configuration hot-reload**: Changes to path mappings in tsconfig.json require restarting the Vite dev server
389
- **Virtual modules**: Modules with `\0` in their ID (Vite virtual modules) are not processed
390