0
# Plugin Configuration
1

2
Core plugin setup and configuration options for customizing component discovery, transformations, and build tool integration across Vite, Webpack, Rollup, esbuild, and Rspack.
3

4
## Capabilities
5

6
### Build Tool Plugins
7

8
Plugin factory functions for different build tools, all sharing the same configuration interface.
9

10
```typescript { .api }
11
/**
12
 * Vite plugin factory with public API access
13
 * @param options - Plugin configuration options
14
 * @returns Vite plugin with attached API for programmatic access
15
 */
16
function VitePlugin(options?: Options): Plugin & { api: PublicPluginAPI };
17

18
/**
19
 * Webpack plugin factory
20
 * @param options - Plugin configuration options
21
 * @returns Webpack plugin instance
22
 */
23
function WebpackPlugin(options?: Options): WebpackPlugin;
24

25
/**
26
 * Rollup plugin factory
27
 * @param options - Plugin configuration options
28
 * @returns Rollup plugin instance
29
 */
30
function RollupPlugin(options?: Options): RollupPlugin;
31

32
/**
33
 * ESBuild plugin factory
34
 * @param options - Plugin configuration options
35
 * @returns ESBuild plugin instance
36
 */
37
function ESBuildPlugin(options?: Options): ESBuildPlugin;
38

39
/**
40
 * Rspack plugin factory
41
 * @param options - Plugin configuration options
42
 * @returns Rspack plugin instance
43
 */
44
function RspackPlugin(options?: Options): RspackPlugin;
45
```
46

47
### File Matching Configuration
48

49
Configure which files should be processed for component auto-importing.
50

51
```typescript { .api }
52
interface FileMatchingOptions {
53
  /** RegExp or glob to match files to be transformed */
54
  include?: FilterPattern;
55
  /** RegExp or glob to match files to NOT be transformed */
56
  exclude?: FilterPattern;
57
  /** RegExp or string to match component names that will NOT be imported */
58
  excludeNames?: FilterPattern;
59
}
60

61
type FilterPattern = string | RegExp | (string | RegExp)[];
62
```
63

64
**Usage Examples:**
65

66
```typescript
67
// Include only Vue files and TypeScript files
68
Components({
69
  include: [/\.vue$/, /\.tsx?$/],
70
  exclude: [/node_modules/, /\.test\.(js|ts)$/],
71
  excludeNames: ["RouterView", "RouterLink"]
72
});
73

74
// Using glob patterns
75
Components({
76
  include: ["**/*.vue", "**/*.tsx"],
77
  exclude: ["**/node_modules/**", "**/*.spec.*"],
78
});
79
```
80

81
### Component Directory Configuration
82

83
Configure how and where components are discovered from the filesystem.
84

85
```typescript { .api }
86
interface DirectoryOptions {
87
  /** Relative paths to directories to search for components */
88
  dirs?: string | string[];
89
  /** Search for subdirectories */
90
  deep?: boolean;
91
  /** Allow subdirectories as namespace prefix for components */
92
  directoryAsNamespace?: boolean;
93
  /** Generate components with prefix */
94
  prefix?: string;
95
  /** Collapse same prefixes of folders and components */
96
  collapseSamePrefixes?: boolean;
97
  /** Subdirectory paths for ignoring namespace prefixes */
98
  globalNamespaces?: string[];
99
}
100
```
101

102
**Usage Examples:**
103

104
```typescript
105
// Multiple component directories
106
Components({
107
  dirs: ["src/components", "src/ui", "src/widgets"],
108
  deep: true,
109
  directoryAsNamespace: true,
110
});
111

112
// Namespace configuration
113
Components({
114
  dirs: ["src/components"],
115
  directoryAsNamespace: true,
116
  globalNamespaces: ["common", "shared"],
117
  collapseSamePrefixes: true,
118
});
119

120
// Component prefix
121
Components({
122
  dirs: ["src/components"],
123
  prefix: "App",
124
});
125
```
126

127
### File Pattern Configuration
128

129
Advanced file discovery using glob patterns instead of directory-based search.
130

131
```typescript { .api }
132
interface GlobOptions {
133
  /** Glob patterns to match file names to be detected as components */
134
  globs?: string | string[];
135
  /** Negated glob patterns to exclude files from being detected as components */
136
  globsExclude?: string | string[];
137
  /** Valid file extensions for components */
138
  extensions?: string | string[];
139
}
140
```
141

142
**Usage Examples:**
143

144
```typescript
145
// Custom glob patterns
146
Components({
147
  globs: ["src/**/components/*.vue", "src/ui/**/*.tsx"],
148
  globsExclude: ["**/*.test.*", "**/*.story.*"],
149
});
150

151
// File extensions
152
Components({
153
  dirs: ["src/components"],
154
  extensions: ["vue", "tsx", "jsx"],
155
});
156
```
157

158
### Vue Configuration
159

160
Vue-specific configuration options for different Vue versions and transformation modes.
161

162
```typescript { .api }
163
interface VueOptions {
164
  /** Vue version of project - auto-detected if not specified */
165
  version?: 2 | 2.7 | 3;
166
  /** Transformer to apply */
167
  transformer?: "vue2" | "vue3";
168
  /** Transform users' usage of resolveComponent/resolveDirective as well */
169
  transformerUserResolveFunctions?: boolean;
170
  /** Auto import for directives */
171
  directives?: boolean;
172
}
173
```
174

175
**Usage Examples:**
176

177
```typescript
178
// Vue 2 configuration
179
Components({
180
  version: 2,
181
  transformer: "vue2",
182
  directives: false, // Requires @babel/parser for Vue 2
183
});
184

185
// Vue 3 with directives
186
Components({
187
  version: 3,
188
  transformer: "vue3",
189
  directives: true,
190
  transformerUserResolveFunctions: true,
191
});
192
```
193

194
### Development and Build Options
195

196
Configuration for TypeScript declarations, source maps, and development features.
197

198
```typescript { .api }
199
interface BuildOptions {
200
  /** Generate TypeScript declaration for global components */
201
  dts?: boolean | string;
202
  /** Generate sourcemap for the transformed code */
203
  sourcemap?: boolean;
204
  /** Save component information into a JSON file for other tools to consume */
205
  dumpComponentsInfo?: boolean | string;
206
  /** Do not emit warning on component overriding */
207
  allowOverrides?: boolean;
208
}
209
```
210

211
**Usage Examples:**
212

213
```typescript
214
// TypeScript declarations
215
Components({
216
  dts: true, // generates components.d.ts
217
  // or custom path
218
  dts: "src/types/components.d.ts",
219
});
220

221
// Development features
222
Components({
223
  sourcemap: true,
224
  dumpComponentsInfo: ".components-info.json",
225
  allowOverrides: false,
226
});
227
```
228

229
### Advanced Configuration
230

231
Advanced options for custom transformations and resolvers.
232

233
```typescript { .api }
234
interface AdvancedOptions {
235
  /** Custom component resolvers */
236
  resolvers?: ComponentResolver[];
237
  /** Custom function to transform the importing path */
238
  importPathTransform?: (path: string) => string | undefined;
239
  /** Only provide types of components in library (registered globally) */
240
  types?: TypeImport[];
241
}
242

243
interface TypeImport {
244
  from: string;
245
  names: string[];
246
}
247
```
248

249
**Usage Examples:**
250

251
```typescript
252
// Custom path transformation
253
Components({
254
  importPathTransform: (path) => {
255
    // Transform absolute paths to relative
256
    return path.replace(/^@\//, "./src/");
257
  },
258
});
259

260
// Type-only imports
261
Components({
262
  types: [
263
    {
264
      from: "vue-router",
265
      names: ["RouteLocationNormalized", "Router"],
266
    },
267
  ],
268
});
269
```
270

271
### Complete Configuration Example
272

273
```typescript
274
// vite.config.ts
275
import { defineConfig } from "vite";
276
import vue from "@vitejs/plugin-vue";
277
import Components from "unplugin-vue-components/vite";
278
import { ElementPlusResolver, AntDesignVueResolver } from "unplugin-vue-components/resolvers";
279

280
export default defineConfig({
281
  plugins: [
282
    vue(),
283
    Components({
284
      // File matching
285
      include: [/\.vue$/, /\.tsx?$/],
286
      exclude: [/node_modules/, /\.test\./],
287
      excludeNames: ["RouterView"],
288
      
289
      // Component discovery
290
      dirs: ["src/components", "src/ui"],
291
      extensions: ["vue", "tsx"],
292
      deep: true,
293
      directoryAsNamespace: true,
294
      globalNamespaces: ["common"],
295
      
296
      // Vue configuration
297
      version: 3,
298
      transformer: "vue3",
299
      directives: true,
300
      
301
      // Build options
302
      dts: "src/types/components.d.ts",
303
      sourcemap: true,
304
      allowOverrides: false,
305
      
306
      // UI library resolvers
307
      resolvers: [
308
        ElementPlusResolver({
309
          importStyle: "sass",
310
        }),
311
        AntDesignVueResolver({
312
          importStyle: false,
313
        }),
314
      ],
315
      
316
      // Advanced options
317
      importPathTransform: (path) => path.replace(/^@\//, "./src/"),
318
    }),
319
  ],
320
});
321
```
322

323
### Other Build Tools Configuration
324

325
Examples for Webpack, Rollup, ESBuild, and Rspack configurations:
326

327
**Webpack Configuration:**
328

329
```javascript
330
// webpack.config.js
331
const Components = require("unplugin-vue-components/webpack");
332

333
module.exports = {
334
  plugins: [
335
    Components({
336
      dirs: ["src/components"],
337
      dts: true,
338
      resolvers: [ElementPlusResolver()],
339
    }),
340
  ],
341
};
342
```
343

344
**Rollup Configuration:**
345

346
```javascript
347
// rollup.config.js
348
import Components from "unplugin-vue-components/rollup";
349

350
export default {
351
  plugins: [
352
    Components({
353
      dirs: ["src/components"],
354
      dts: true,
355
      resolvers: [ElementPlusResolver()],
356
    }),
357
  ],
358
};
359
```
360

361
**ESBuild Configuration:**
362

363
```javascript
364
// esbuild.config.js
365
import { build } from "esbuild";
366
import Components from "unplugin-vue-components/esbuild";
367

368
build({
369
  plugins: [
370
    Components({
371
      dirs: ["src/components"],
372
      dts: true,
373
      resolvers: [ElementPlusResolver()],
374
    }),
375
  ],
376
});
377
```
378

379
**Rspack Configuration:**
380

381
```javascript
382
// rspack.config.js
383
const Components = require("unplugin-vue-components/rspack");
384

385
module.exports = {
386
  plugins: [
387
    Components({
388
      dirs: ["src/components"],
389
      dts: true,
390
      resolvers: [ElementPlusResolver()],
391
    }),
392
  ],
393
};
394
```