0
# Nuxt Integration
1

2
Dedicated Nuxt module providing seamless integration with Nuxt's auto-import system and server-side rendering support.
3

4
## Capabilities
5

6
### Nuxt Module Setup
7

8
Dedicated Nuxt module that integrates with both Vite and Webpack configurations automatically.
9

10
```typescript { .api }
11
/**
12
 * Nuxt module for unplugin-vue-components
13
 * @param options - Plugin configuration options
14
 * @returns Nuxt module definition
15
 */
16
declare function NuxtModule(options?: Options): NuxtModule;
17

18
/**
19
 * Nuxt module configuration in nuxt.config.ts
20
 */
21
interface NuxtConfig {
22
  modules: string[];
23
  components?: ComponentsModuleOptions;
24
}
25

26
interface ComponentsModuleOptions extends Options {
27
  /** Nuxt-specific component configuration */
28
  nuxtSpecific?: boolean;
29
}
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
// nuxt.config.ts
36
export default defineNuxtConfig({
37
  modules: ["unplugin-vue-components/nuxt"],
38
  
39
  // Optional: Configure via components key
40
  components: {
41
    dirs: ["components", "~/components/ui"],
42
    extensions: ["vue"],
43
    dts: true,
44
  },
45
});
46

47
// Alternative: Direct module configuration
48
export default defineNuxtConfig({
49
  modules: [
50
    ["unplugin-vue-components/nuxt", {
51
      dirs: ["components"],
52
      resolvers: [ElementPlusResolver()],
53
    }],
54
  ],
55
});
56
```
57

58
### Server-Side Rendering Support
59

60
Full SSR compatibility with proper hydration and server-side component resolution.
61

62
```typescript { .api }
63
/**
64
 * SSR-specific configuration options
65
 */
66
interface SSROptions {
67
  /** Enable SSR mode for compatible resolvers */
68
  ssr?: boolean;
69
  /** Server-side component resolution */
70
  serverComponents?: boolean;
71
}
72
```
73

74
**Usage Examples:**
75

76
```typescript
77
// nuxt.config.ts with SSR configuration
78
export default defineNuxtConfig({
79
  modules: ["unplugin-vue-components/nuxt"],
80
  
81
  components: {
82
    dirs: ["components"],
83
    
84
    // SSR-compatible resolvers
85
    resolvers: [
86
      ElementPlusResolver({
87
        ssr: true, // Use CommonJS for SSR
88
        importStyle: "css", // Use CSS instead of Sass for SSR
89
      }),
90
    ],
91
    
92
    dts: true,
93
  },
94
  
95
  ssr: true, // Nuxt SSR enabled
96
});
97
```
98

99
### Nuxt Auto-Import Integration
100

101
Seamless integration with Nuxt's built-in auto-import system.
102

103
```typescript { .api }
104
/**
105
 * Nuxt auto-import integration options
106
 */
107
interface NuxtAutoImportOptions {
108
  /** Integration with Nuxt's auto-imports */
109
  nuxtAutoImports?: boolean;
110
  /** Global component registration */
111
  globalComponents?: boolean;
112
}
113
```
114

115
**Usage Examples:**
116

117
```typescript
118
// Automatic integration with Nuxt auto-imports
119
export default defineNuxtConfig({
120
  modules: ["unplugin-vue-components/nuxt"],
121
  
122
  components: {
123
    dirs: [
124
      "components", // Standard Nuxt components directory
125
      "~/components/ui", // Additional UI components
126
      "~/components/layout", // Layout components
127
    ],
128
    
129
    // Works alongside Nuxt's built-in component auto-import
130
    directoryAsNamespace: false, // Let Nuxt handle namespacing
131
    global: true, // Register components globally
132
  },
133
});
134
```
135

136
### Layer Support
137

138
Support for Nuxt layers and component inheritance.
139

140
**Usage Examples:**
141

142
```typescript
143
// nuxt.config.ts in base layer
144
export default defineNuxtConfig({
145
  modules: ["unplugin-vue-components/nuxt"],
146
  
147
  components: {
148
    dirs: ["components/base"],
149
    resolvers: [ElementPlusResolver()],
150
  },
151
});
152

153
// nuxt.config.ts in extending project  
154
export default defineNuxtConfig({
155
  extends: ["./layers/base"],
156
  
157
  modules: ["unplugin-vue-components/nuxt"],
158
  
159
  components: {
160
    dirs: [
161
      "components", // Project-specific components
162
      "components/override", // Override base layer components
163
    ],
164
    allowOverrides: true, // Allow overriding base layer components
165
  },
166
});
167
```
168

169
### Development vs Production
170

171
Different configurations for development and production in Nuxt context.
172

173
**Usage Examples:**
174

175
```typescript
176
export default defineNuxtConfig({
177
  modules: ["unplugin-vue-components/nuxt"],
178
  
179
  components: {
180
    dirs: ["components"],
181
    
182
    // Development-specific options
183
    ...(process.env.NODE_ENV === "development" && {
184
      dts: true,
185
      allowOverrides: true,
186
      sourcemap: true,
187
    }),
188
    
189
    // Production-specific options
190
    ...(process.env.NODE_ENV === "production" && {
191
      dts: false, // Skip in production build
192
      sourcemap: false,
193
    }),
194
    
195
    resolvers: [
196
      ElementPlusResolver({
197
        importStyle: process.env.NODE_ENV === "development" ? "sass" : "css",
198
      }),
199
    ],
200
  },
201
});
202
```
203

204
### Nuxt DevTools Integration
205

206
Integration with Nuxt DevTools for component inspection and debugging.
207

208
**Usage Examples:**
209

210
```typescript
211
export default defineNuxtConfig({
212
  modules: ["unplugin-vue-components/nuxt"],
213
  
214
  devtools: { enabled: true },
215
  
216
  components: {
217
    dirs: ["components"],
218
    dts: true, // Required for DevTools component inspection
219
    
220
    // Enhanced debugging information
221
    dumpComponentsInfo: process.env.NODE_ENV === "development",
222
  },
223
});
224
```
225

226
### TypeScript Configuration for Nuxt
227

228
Optimal TypeScript setup for Nuxt projects using unplugin-vue-components.
229

230
```typescript { .api }
231
/**
232
 * Nuxt TypeScript integration
233
 */
234
interface NuxtTypeScriptOptions {
235
  /** Generate .nuxt/components.d.ts */
236
  dts?: boolean | string;
237
  /** TypeScript strict mode compatibility */
238
  strict?: boolean;
239
}
240
```
241

242
**Usage Examples:**
243

244
```typescript
245
// nuxt.config.ts
246
export default defineNuxtConfig({
247
  modules: ["unplugin-vue-components/nuxt"],
248
  
249
  typescript: {
250
    strict: true,
251
    typeCheck: true,
252
  },
253
  
254
  components: {
255
    dirs: ["components"],
256
    dts: true, // Generates .nuxt/components.d.ts
257
    
258
    resolvers: [
259
      ElementPlusResolver(),
260
      AntDesignVueResolver(),
261
    ],
262
  },
263
});
264

265
// .nuxt/components.d.ts will be automatically generated
266
// and included in TypeScript compilation
267
```
268

269
### Nuxt 3 Composition API
270

271
Optimal configuration for Nuxt 3 with Composition API and script setup.
272

273
**Usage Examples:**
274

275
```typescript
276
// nuxt.config.ts for Nuxt 3
277
export default defineNuxtConfig({
278
  modules: ["unplugin-vue-components/nuxt"],
279
  
280
  components: {
281
    dirs: ["components"],
282
    
283
    // Nuxt 3 optimizations
284
    version: 3,
285
    transformer: "vue3",
286
    transformerUserResolveFunctions: true,
287
    
288
    // Full TypeScript support
289
    dts: true,
290
  },
291
});
292

293
// In your Nuxt 3 pages/components
294
// <script setup lang="ts">
295
// // Components auto-imported with full typing
296
// const title = "My Page";
297
// </script>
298
//
299
// <template>
300
//   <div>
301
//     <MyComponent :title="title" />
302
//     <ElButton type="primary">Click me</ElButton>
303
//   </div>
304
// </template>
305
```
306

307
### Module Options vs Components Config
308

309
Different ways to configure the module in Nuxt.
310

311
**Usage Examples:**
312

313
```typescript
314
// Method 1: Direct module configuration
315
export default defineNuxtConfig({
316
  modules: [
317
    ["unplugin-vue-components/nuxt", {
318
      dirs: ["components"],
319
      resolvers: [ElementPlusResolver()],
320
      dts: true,
321
    }],
322
  ],
323
});
324

325
// Method 2: Components configuration key (recommended)
326
export default defineNuxtConfig({
327
  modules: ["unplugin-vue-components/nuxt"],
328
  
329
  components: {
330
    dirs: ["components"],
331
    resolvers: [ElementPlusResolver()],
332
    dts: true,
333
  },
334
});
335

336
// Method 3: Runtime configuration
337
export default defineNuxtConfig({
338
  modules: ["unplugin-vue-components/nuxt"],
339
  
340
  runtimeConfig: {
341
    components: {
342
      // Runtime-specific component settings
343
    },
344
  },
345
  
346
  components: {
347
    dirs: ["components"],
348
  },
349
});
350
```
351

352
### Nuxt Compatibility
353

354
Version compatibility and migration guidance.
355

356
**Usage Examples:**
357

358
```typescript
359
// Nuxt 2 configuration (legacy)
360
export default {
361
  buildModules: ["unplugin-vue-components/nuxt"],
362
  
363
  components: {
364
    dirs: ["components"],
365
    version: 2,
366
    transformer: "vue2",
367
  },
368
};
369

370
// Nuxt 3 configuration (current)
371
export default defineNuxtConfig({
372
  modules: ["unplugin-vue-components/nuxt"],
373
  
374
  components: {
375
    dirs: ["components"],
376
    version: 3,
377
    transformer: "vue3",
378
  },
379
});
380

381
// Nuxt Bridge configuration
382
export default defineNuxtConfig({
383
  bridge: true,
384
  modules: ["unplugin-vue-components/nuxt"],
385
  
386
  components: {
387
    dirs: ["components"],
388
    version: 2.7, // Vue 2.7 with Composition API
389
  },
390
});
391
```
392

393
### Advanced Nuxt Integration
394

395
Advanced patterns for complex Nuxt applications.
396

397
**Usage Examples:**
398

399
```typescript
400
// Multi-tenant Nuxt application
401
export default defineNuxtConfig({
402
  modules: ["unplugin-vue-components/nuxt"],
403
  
404
  components: {
405
    dirs: [
406
      "components/shared",
407
      `components/tenants/${process.env.TENANT}`,
408
    ],
409
    allowOverrides: true,
410
    
411
    resolvers: [
412
      // Tenant-specific resolver
413
      (name: string) => {
414
        const tenant = process.env.TENANT;
415
        if (name.startsWith("Tenant")) {
416
          return {
417
            name,
418
            from: `@/components/tenants/${tenant}/${name}.vue`,
419
          };
420
        }
421
      },
422
    ],
423
  },
424
});
425

426
// Nuxt with module federation
427
export default defineNuxtConfig({
428
  modules: ["unplugin-vue-components/nuxt"],
429
  
430
  components: {
431
    dirs: ["components/local"],
432
    
433
    resolvers: [
434
      // Remote component resolver
435
      (name: string) => {
436
        if (name.startsWith("Remote")) {
437
          return {
438
            name,
439
            from: `@remote-app/components/${name}`,
440
          };
441
        }
442
      },
443
    ],
444
  },
445
});
446
```