0
# unplugin-vue-components
1
2
unplugin-vue-components is a universal Vue component auto-importing plugin that works across multiple build tools including Vite, Webpack, Rollup, esbuild, and Rspack. It automatically imports Vue components on-demand from local directories or popular UI libraries, eliminating the need for manual component registration and significantly reducing boilerplate code while maintaining full TypeScript support and tree-shaking optimization.
3
4
## Package Information
5
6
- **Package Name**: unplugin-vue-components
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install unplugin-vue-components`
10
11
## Core Imports
12
13
```typescript
14
import Components from "unplugin-vue-components/vite";
15
```
16
17
For other build tools:
18
19
```typescript
20
import Components from "unplugin-vue-components/webpack";
21
import Components from "unplugin-vue-components/rollup";
22
import Components from "unplugin-vue-components/esbuild";
23
import Components from "unplugin-vue-components/rspack";
24
```
25
26
For Nuxt:
27
28
```typescript
29
import Components from "unplugin-vue-components/nuxt";
30
```
31
32
Resolvers for UI libraries:
33
34
```typescript
35
import { ElementPlusResolver, AntDesignVueResolver } from "unplugin-vue-components/resolvers";
36
```
37
38
Utility functions:
39
40
```typescript
41
import { camelCase, kebabCase, pascalCase } from "unplugin-vue-components";
42
```
43
44
Type definitions:
45
46
```typescript
47
import type { Options, ComponentInfo, ComponentResolver } from "unplugin-vue-components/types";
48
```
49
50
## Basic Usage
51
52
```typescript
53
// vite.config.ts
54
import { defineConfig } from "vite";
55
import vue from "@vitejs/plugin-vue";
56
import Components from "unplugin-vue-components/vite";
57
58
export default defineConfig({
59
plugins: [
60
vue(),
61
Components({
62
// Auto import components from src/components directory
63
dirs: ["src/components"],
64
// Generate TypeScript declarations
65
dts: true,
66
// Auto import from UI libraries
67
resolvers: [ElementPlusResolver()],
68
}),
69
],
70
});
71
```
72
73
After setup, use components directly in Vue templates without imports:
74
75
```vue
76
<template>
77
<!-- Local component auto-imported from src/components/HelloWorld.vue -->
78
<HelloWorld />
79
80
<!-- UI library component auto-imported via resolver -->
81
<ElButton type="primary">Click me</ElButton>
82
</template>
83
84
<script setup lang="ts">
85
// No manual imports needed - components are auto-imported!
86
</script>
87
```
88
89
## Architecture
90
91
unplugin-vue-components is built around several key components:
92
93
- **Universal Plugin**: Uses `unplugin` framework to provide consistent API across all build tools
94
- **Context System**: Centralized component discovery and caching with file watching capabilities
95
- **Resolver System**: Extensible component resolution with built-in support for 20+ UI libraries
96
- **Transformer Engine**: Vue 2/3 compatible code transformations with TypeScript support
97
- **Declaration Generator**: Automatic TypeScript declaration generation for IDE intellisense
98
99
## Capabilities
100
101
### Plugin Configuration
102
103
Core plugin setup and configuration options for customizing component discovery, transformations, and build tool integration.
104
105
```typescript { .api }
106
interface Options {
107
include?: FilterPattern;
108
exclude?: FilterPattern;
109
dirs?: string | string[];
110
extensions?: string | string[];
111
resolvers?: ComponentResolver[];
112
dts?: boolean | string;
113
transformer?: "vue2" | "vue3";
114
}
115
116
// Build tool specific plugin functions
117
function VitePlugin(options?: Options): Plugin & { api: PublicPluginAPI };
118
function WebpackPlugin(options?: Options): WebpackPlugin;
119
function RollupPlugin(options?: Options): RollupPlugin;
120
```
121
122
[Plugin Configuration](./plugin-configuration.md)
123
124
### Component Resolution
125
126
Built-in component discovery from directories and extensible resolver system for UI libraries, with support for custom resolution logic.
127
128
```typescript { .api }
129
type ComponentResolver = ComponentResolverFunction | ComponentResolverObject;
130
131
interface ComponentResolverFunction {
132
(name: string): ComponentResolveResult;
133
}
134
135
interface ComponentResolverObject {
136
type: "component" | "directive";
137
resolve: ComponentResolverFunction;
138
}
139
140
type ComponentResolveResult = string | ComponentInfo | null | undefined | void;
141
```
142
143
[Component Resolution](./component-resolution.md)
144
145
### UI Library Resolvers
146
147
Pre-built resolvers for popular Vue UI libraries including Element Plus, Ant Design Vue, Vuetify, Quasar, and many others.
148
149
```typescript { .api }
150
function ElementPlusResolver(options?: ElementPlusResolverOptions): ComponentResolver;
151
function AntDesignVueResolver(options?: AntDesignVueResolverOptions): ComponentResolver;
152
function VuetifyResolver(options?: VuetifyResolverOptions): ComponentResolver;
153
```
154
155
[UI Library Resolvers](./ui-library-resolvers.md)
156
157
### TypeScript Integration
158
159
Automatic TypeScript declaration generation and type-safe configuration with full IDE intellisense support.
160
161
```typescript { .api }
162
interface PublicPluginAPI {
163
findComponent(name: string, filename?: string): Promise<ComponentInfo | undefined>;
164
stringifyImport(info: ComponentInfo): string;
165
}
166
167
interface ComponentInfo {
168
as?: string;
169
name?: string;
170
from: string;
171
sideEffects?: SideEffectsInfo;
172
}
173
```
174
175
[TypeScript Integration](./typescript-integration.md)
176
177
### Utility Functions
178
179
String transformation utilities for consistent component naming conventions across Vue applications.
180
181
```typescript { .api }
182
function camelCase(str: string): string;
183
function kebabCase(str: string): string;
184
function pascalCase(str: string): string;
185
```
186
187
### Nuxt Integration
188
189
Dedicated Nuxt module providing seamless integration with Nuxt's auto-import system and server-side rendering support.
190
191
```typescript { .api }
192
// nuxt.config.ts
193
export default defineNuxtModule({
194
modules: ["unplugin-vue-components/nuxt"],
195
components: {
196
// Configuration options
197
},
198
});
199
```
200
201
[Nuxt Integration](./nuxt-integration.md)
202
203
## Types
204
205
### Core Configuration Types
206
207
```typescript { .api }
208
interface Options {
209
/** RegExp or glob to match files to be transformed */
210
include?: FilterPattern;
211
/** RegExp or glob to match files to NOT be transformed */
212
exclude?: FilterPattern;
213
/** RegExp or string to match component names that will NOT be imported */
214
excludeNames?: FilterPattern;
215
/** Relative paths to the directory to search for components */
216
dirs?: string | string[];
217
/** Valid file extensions for components */
218
extensions?: string | string[];
219
/** Glob patterns to match file names to be detected as components */
220
globs?: string | string[];
221
/** Negated glob patterns to exclude files from being detected as components */
222
globsExclude?: string | string[];
223
/** Search for subdirectories */
224
deep?: boolean;
225
/** Allow subdirectories as namespace prefix for components */
226
directoryAsNamespace?: boolean;
227
/** Generate components with prefix */
228
prefix?: string;
229
/** Collapse same prefixes of folders and components */
230
collapseSamePrefixes?: boolean;
231
/** Subdirectory paths for ignoring namespace prefixes */
232
globalNamespaces?: string[];
233
/** Custom component resolvers */
234
resolvers?: ComponentResolver[];
235
/** Custom function to transform the importing path */
236
importPathTransform?: (path: string) => string | undefined;
237
/** Transformer to apply */
238
transformer?: "vue2" | "vue3";
239
/** Transform users' usage of resolveComponent/resolveDirective as well */
240
transformerUserResolveFunctions?: boolean;
241
/** Generate TypeScript declaration for global components */
242
dts?: boolean | string;
243
/** Do not emit warning on component overriding */
244
allowOverrides?: boolean;
245
/** Auto import for directives */
246
directives?: boolean;
247
/** Only provide types of components in library */
248
types?: TypeImport[];
249
/** Vue version of project */
250
version?: 2 | 2.7 | 3;
251
/** Generate sourcemap for the transformed code */
252
sourcemap?: boolean;
253
/** Save component information into a JSON file */
254
dumpComponentsInfo?: boolean | string;
255
}
256
257
type FilterPattern = string | RegExp | (string | RegExp)[];
258
```
259
260
### Component Information Types
261
262
```typescript { .api }
263
interface ComponentInfo {
264
/** Import alias name */
265
as?: string;
266
/** Component name */
267
name?: string;
268
/** Import path */
269
from: string;
270
/** Side effect imports */
271
sideEffects?: SideEffectsInfo;
272
}
273
274
interface ImportInfo {
275
/** Import alias */
276
as?: string;
277
/** Import name */
278
name?: string;
279
/** Import source */
280
from: string;
281
}
282
283
type SideEffectsInfo = (ImportInfo | string)[] | ImportInfo | string | undefined;
284
285
interface TypeImport {
286
/** Import source */
287
from: string;
288
/** Type names to import */
289
names: string[];
290
}
291
```
292
293
### Plugin API Types
294
295
```typescript { .api }
296
interface PublicPluginAPI {
297
/** Resolves a component using the configured resolvers */
298
findComponent(name: string, filename?: string): Promise<ComponentInfo | undefined>;
299
/** Obtain an import statement for a resolved component */
300
stringifyImport(info: ComponentInfo): string;
301
}
302
303
type ComponentResolveResult = string | ComponentInfo | null | undefined | void;
304
305
type ComponentResolverFunction = (name: string) => ComponentResolveResult;
306
307
interface ComponentResolverObject {
308
type: "component" | "directive";
309
resolve: ComponentResolverFunction;
310
}
311
312
type ComponentResolver = ComponentResolverFunction | ComponentResolverObject;
313
```