0
# TypeScript Integration
1
2
Automatic TypeScript declaration generation and type-safe configuration with full IDE intellisense support for auto-imported components.
3
4
## Capabilities
5
6
### Declaration Generation
7
8
Automatic generation of TypeScript declarations for globally available components, providing full IDE intellisense and type checking.
9
10
```typescript { .api }
11
/**
12
* TypeScript declaration configuration
13
*/
14
interface DeclarationOptions {
15
/** Generate TypeScript declaration for global components */
16
dts?: boolean | string;
17
/** Only provide types of components in library (registered globally) */
18
types?: TypeImport[];
19
}
20
21
interface TypeImport {
22
/** Import source module */
23
from: string;
24
/** Type names to import */
25
names: string[];
26
}
27
```
28
29
**Usage Examples:**
30
31
```typescript
32
// Basic declaration generation
33
Components({
34
dts: true, // Generates components.d.ts in project root
35
});
36
37
// Custom declaration file path
38
Components({
39
dts: "src/types/auto-components.d.ts",
40
});
41
42
// Type-only imports for global components
43
Components({
44
types: [
45
{
46
from: "vue-router",
47
names: ["RouterLink", "RouterView"],
48
},
49
{
50
from: "@/types/global-components",
51
names: ["GlobalHeader", "GlobalFooter"],
52
},
53
],
54
});
55
```
56
57
### Plugin API
58
59
Public API for programmatic access to component resolution and import generation.
60
61
```typescript { .api }
62
/**
63
* Public plugin API interface
64
*/
65
interface PublicPluginAPI {
66
/** Resolves a component using the configured resolvers */
67
findComponent(name: string, filename?: string): Promise<ComponentInfo | undefined>;
68
/** Obtain an import statement for a resolved component */
69
stringifyImport(info: ComponentInfo): string;
70
}
71
72
/**
73
* Component information interface
74
*/
75
interface ComponentInfo {
76
/** Import alias name */
77
as?: string;
78
/** Component name */
79
name?: string;
80
/** Import path or module name */
81
from: string;
82
/** Side effect imports (CSS, etc.) */
83
sideEffects?: SideEffectsInfo;
84
}
85
```
86
87
**Usage Examples:**
88
89
```typescript
90
// Access plugin API in Vite
91
import Components from "unplugin-vue-components/vite";
92
93
const plugin = Components({
94
dirs: ["src/components"],
95
});
96
97
// Plugin API is available on the returned plugin
98
export default defineConfig({
99
plugins: [
100
vue(),
101
plugin,
102
],
103
});
104
105
// Use API programmatically
106
const api = plugin.api;
107
const component = await api.findComponent("MyButton");
108
if (component) {
109
const importStatement = api.stringifyImport(component);
110
console.log(importStatement); // import MyButton from '@/components/MyButton.vue'
111
}
112
```
113
114
### Type Safety Configuration
115
116
Configuration options that ensure type safety throughout the plugin operation.
117
118
```typescript { .api }
119
/**
120
* Type-safe configuration interface
121
*/
122
interface TypeSafeOptions {
123
/** Vue version for proper type generation */
124
version?: 2 | 2.7 | 3;
125
/** Transformer selection affects type generation */
126
transformer?: "vue2" | "vue3";
127
/** Allow component overrides without warnings */
128
allowOverrides?: boolean;
129
}
130
```
131
132
**Usage Examples:**
133
134
```typescript
135
// Explicit Vue version for accurate types
136
Components({
137
version: 3, // Ensures Vue 3 component types
138
transformer: "vue3",
139
dts: true,
140
});
141
142
// Type-safe overrides
143
Components({
144
allowOverrides: false, // Warn about component name conflicts
145
dts: true,
146
});
147
```
148
149
### Generated Declaration Structure
150
151
The structure and content of automatically generated TypeScript declarations.
152
153
```typescript { .api }
154
/**
155
* Example generated declaration file structure
156
*/
157
declare module "@vue/runtime-core" {
158
export interface GlobalComponents {
159
// Local components
160
HelloWorld: typeof import("./src/components/HelloWorld.vue")["default"];
161
MyButton: typeof import("./src/components/MyButton.vue")["default"];
162
163
// UI library components (via resolvers)
164
ElButton: typeof import("element-plus")["ElButton"];
165
ElCard: typeof import("element-plus")["ElCard"];
166
167
// Namespaced components
168
FormInput: typeof import("./src/components/form/Input.vue")["default"];
169
FormSelect: typeof import("./src/components/form/Select.vue")["default"];
170
}
171
}
172
173
export {};
174
```
175
176
### IDE Integration
177
178
Configuration for optimal IDE experience with auto-imported components.
179
180
**Usage Examples:**
181
182
```typescript
183
// VS Code integration
184
Components({
185
dts: true,
186
// Ensure declarations are updated during development
187
dirs: ["src/components"],
188
deep: true,
189
// Enable for better IntelliSense
190
directoryAsNamespace: true,
191
});
192
193
// WebStorm/IntelliJ integration
194
Components({
195
dts: "types/components.d.ts", // Place in types directory
196
extensions: ["vue", "tsx"], // Support all relevant file types
197
});
198
```
199
200
### Vue 3 Composition API Types
201
202
Special handling for Vue 3 Composition API and TypeScript integration.
203
204
```typescript { .api }
205
/**
206
* Vue 3 specific type configuration
207
*/
208
interface Vue3TypeOptions {
209
/** Transform user resolve functions for better TypeScript support */
210
transformerUserResolveFunctions?: boolean;
211
/** Support for script setup syntax */
212
scriptSetup?: boolean;
213
}
214
```
215
216
**Usage Examples:**
217
218
```typescript
219
// Vue 3 + TypeScript + script setup
220
Components({
221
version: 3,
222
transformer: "vue3",
223
transformerUserResolveFunctions: true,
224
dts: true,
225
});
226
227
// In your Vue components
228
// <script setup lang="ts">
229
// // No imports needed - components are auto-imported with full typing
230
// </script>
231
//
232
// <template>
233
// <HelloWorld /> <!-- Fully typed! -->
234
// <ElButton type="primary" /> <!-- UI library types work too! -->
235
// </template>
236
```
237
238
### Custom Type Definitions
239
240
Adding custom type definitions for complex component scenarios.
241
242
```typescript { .api }
243
/**
244
* Custom type definition configuration
245
*/
246
interface CustomTypeOptions {
247
/** Additional type imports */
248
types?: TypeImport[];
249
/** Path transformation for custom types */
250
importPathTransform?: (path: string) => string | undefined;
251
}
252
```
253
254
**Usage Examples:**
255
256
```typescript
257
// Custom global component types
258
Components({
259
dts: true,
260
types: [
261
// Global layout components
262
{
263
from: "@/layouts",
264
names: ["DefaultLayout", "AdminLayout"],
265
},
266
// Third-party components not handled by resolvers
267
{
268
from: "my-custom-ui-lib",
269
names: ["CustomButton", "CustomModal"],
270
},
271
],
272
});
273
274
// With path transformation
275
Components({
276
dts: true,
277
importPathTransform: (path) => {
278
// Transform @ alias in type definitions
279
return path.replace(/^@\//, "./src/");
280
},
281
});
282
```
283
284
### Development vs Production Types
285
286
Different type generation strategies for development and production.
287
288
**Usage Examples:**
289
290
```typescript
291
const isDev = process.env.NODE_ENV === "development";
292
293
Components({
294
// More detailed types in development
295
dts: isDev ? "src/types/components.development.d.ts" : true,
296
297
// More permissive in development
298
allowOverrides: isDev,
299
300
// Additional checks in development
301
version: 3,
302
transformer: "vue3",
303
});
304
```
305
306
### Type Checking Integration
307
308
Integration with TypeScript compiler and type checking tools.
309
310
**Usage Examples:**
311
312
```typescript
313
// package.json scripts
314
{
315
"scripts": {
316
"type-check": "vue-tsc --noEmit",
317
"build": "vue-tsc && vite build"
318
}
319
}
320
321
// tsconfig.json
322
{
323
"compilerOptions": {
324
"types": ["node", "vite/client"]
325
},
326
"include": [
327
"src/**/*",
328
"components.d.ts" // Include generated declarations
329
]
330
}
331
332
// vite.config.ts with type checking
333
Components({
334
dts: true,
335
// Ensure types are generated before TypeScript compilation
336
dirs: ["src/components"],
337
});
338
```
339
340
### Declaration File Maintenance
341
342
Best practices for maintaining generated declaration files.
343
344
**Usage Examples:**
345
346
```typescript
347
// .gitignore - whether to commit generated declarations
348
# Option 1: Commit for team consistency (recommended)
349
# components.d.ts
350
351
# Option 2: Don't commit, generate locally
352
components.d.ts
353
354
// Auto-regeneration during development
355
Components({
356
dts: true,
357
// Will update declarations when components change
358
dirs: ["src/components"],
359
extensions: ["vue", "tsx"],
360
});
361
```
362
363
### Troubleshooting TypeScript Issues
364
365
Common TypeScript integration issues and solutions.
366
367
**Usage Examples:**
368
369
```typescript
370
// Issue: Components not recognized by TypeScript
371
// Solution: Ensure declaration file is generated and included
372
373
Components({
374
dts: true, // Make sure this is enabled
375
});
376
377
// Check tsconfig.json includes the declaration file
378
{
379
"include": ["src/**/*", "components.d.ts"]
380
}
381
382
// Issue: Wrong component types
383
// Solution: Specify correct Vue version and transformer
384
385
Components({
386
version: 3, // Match your actual Vue version
387
transformer: "vue3",
388
dts: true,
389
});
390
391
// Issue: Resolver components not typed
392
// Solution: Use resolvers that support TypeScript
393
394
Components({
395
resolvers: [
396
ElementPlusResolver(), // Has built-in TypeScript support
397
],
398
dts: true,
399
});
400
```