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
```