0
# Plugins & Templates
1

2
Plugin registration and template generation for virtual file system and TypeScript support. Manages both runtime plugins and build-time template generation.
3

4
## Capabilities
5

6
### Plugin Registration
7

8
Register Nuxt plugins for client-side, server-side, or universal execution.
9

10
```typescript { .api }
11
/**
12
 * Register a Nuxt plugin
13
 * @param plugin - Plugin file path or plugin object
14
 * @param opts - Plugin registration options
15
 * @returns Normalized NuxtPlugin object
16
 */
17
function addPlugin(
18
  plugin: NuxtPlugin | string,
19
  opts?: AddPluginOptions
20
): NuxtPlugin;
21

22
/**
23
 * Add template and register as plugin
24
 * @param plugin - Plugin template or file path
25
 * @param opts - Plugin registration options
26
 * @returns Normalized NuxtPlugin object
27
 */
28
function addPluginTemplate(
29
  plugin: NuxtPluginTemplate | string,
30
  opts?: AddPluginOptions
31
): NuxtPlugin;
32

33
/**
34
 * Normalize plugin object
35
 * @param plugin - Plugin to normalize
36
 * @returns Normalized NuxtPlugin object
37
 */
38
function normalizePlugin(plugin: NuxtPlugin | string): NuxtPlugin;
39

40
interface NuxtPlugin {
41
  /** Plugin source code or file path */
42
  src: string;
43
  /** Plugin execution mode */
44
  mode?: PluginMode;
45
  /** Plugin runs only once */
46
  ssr?: boolean;
47
  /** Plugin name */
48
  name?: string;
49
  /** Plugin priority */
50
  order?: number;
51
  /** Plugin environment */
52
  env?: PluginEnv;
53
  /** Plugin metadata */
54
  meta?: PluginMeta;
55
}
56

57
type PluginMode = "client" | "server" | "all";
58
type PluginEnv = { islands?: boolean };
59

60
interface AddPluginOptions {
61
  /** Append plugin to end of array */
62
  append?: boolean;
63
  /** Prepend plugin to beginning of array */
64
  prepend?: boolean;
65
}
66

67
interface PluginMeta {
68
  /** Plugin name */
69
  name?: string;
70
  /** Plugin version */
71
  version?: string;
72
  [key: string]: any;
73
}
74
```
75

76
**Usage Examples:**
77

78
```typescript
79
import { addPlugin, addPluginTemplate } from "@nuxt/kit";
80

81
// Add existing plugin file
82
addPlugin("~/plugins/my-plugin.client.js");
83

84
// Add plugin with options
85
addPlugin({
86
  src: "~/plugins/analytics.js",
87
  mode: "client",
88
  name: "analytics-plugin"
89
});
90

91
// Add plugin template
92
addPluginTemplate({
93
  src: "~/templates/api-plugin.mjs",
94
  filename: "api-plugin.mjs",
95
  options: {
96
    apiEndpoint: "https://api.example.com",
97
    timeout: 5000
98
  }
99
});
100

101
// Add inline plugin
102
addPlugin({
103
  name: "inline-setup",
104
  setup() {
105
    // Plugin code here
106
    console.log("Plugin initialized");
107
  }
108
});
109
```
110

111
### Template System
112

113
Generate virtual files and manage the template system for build-time code generation.
114

115
```typescript { .api }
116
/**
117
 * Add template to virtual file system
118
 * @param template - Template configuration or file path
119
 * @returns Resolved template object
120
 */
121
function addTemplate<T>(template: NuxtTemplate<T> | string): ResolvedNuxtTemplate<T>;
122

123
/**
124
 * Add virtual file for Nuxt Nitro server build
125
 * @param template - Server template configuration
126
 * @returns Server template object
127
 */
128
function addServerTemplate(template: NuxtServerTemplate): NuxtServerTemplate;
129

130
/**
131
 * Add type template and register as TypeScript reference
132
 * @param template - Type template configuration
133
 * @param context - Template context options
134
 * @returns Resolved template object
135
 */
136
function addTypeTemplate<T>(
137
  template: NuxtTypeTemplate<T>,
138
  context?: { nitro?: boolean; nuxt?: boolean }
139
): ResolvedNuxtTemplate<T>;
140

141
/**
142
 * Normalize template object
143
 * @param template - Template to normalize
144
 * @param buildDir - Build directory path
145
 * @returns Resolved template object
146
 */
147
function normalizeTemplate<T>(
148
  template: NuxtTemplate<T> | string,
149
  buildDir?: string
150
): ResolvedNuxtTemplate<T>;
151

152
interface NuxtTemplate<T = Record<string, any>> {
153
  /** Template source file path */
154
  src?: string;
155
  /** Output filename */
156
  filename?: string;
157
  /** Template destination path */
158
  dst?: string;
159
  /** Template data/options */
160
  options?: T;
161
  /** Template content generator */
162
  getContents?: (data: T) => string | Promise<string>;
163
  /** Write template to filesystem */
164
  write?: boolean;
165
  /** Template metadata */
166
  meta?: TemplateMeta;
167
}
168

169
interface ResolvedNuxtTemplate<T = Record<string, any>> extends NuxtTemplate<T> {
170
  /** Resolved destination path */
171
  dst: string;
172
  /** Resolved filename */
173
  filename: string;
174
}
175

176
interface TemplateMeta {
177
  /** Template component */
178
  component?: boolean;
179
  [key: string]: any;
180
}
181
```
182

183
**Usage Examples:**
184

185
```typescript
186
import { addTemplate, addTypeTemplate, addServerTemplate } from "@nuxt/kit";
187

188
// Add simple template
189
addTemplate({
190
  filename: "my-config.mjs",
191
  getContents: () => `export default ${JSON.stringify(myConfig)}`
192
});
193

194
// Add template with data
195
addTemplate({
196
  src: "templates/api-client.mjs",
197
  filename: "api-client.mjs",
198
  options: {
199
    baseURL: "https://api.example.com",
200
    timeout: 5000
201
  }
202
});
203

204
// Add TypeScript type template
205
addTypeTemplate({
206
  filename: "types/my-module.d.ts",
207
  getContents: () => `
208
    declare module '#app' {
209
      interface NuxtApp {
210
        $myModule: MyModuleInterface
211
      }
212
    }
213
    
214
    export interface MyModuleInterface {
215
      method(): void;
216
    }
217
  `
218
});
219

220
// Add server-only template
221
addServerTemplate({
222
  src: "templates/server-utils.mjs",
223
  filename: "server-utils.mjs"
224
});
225
```
226

227
### Plugin Templates
228

229
Combine plugins with templates for dynamic plugin generation.
230

231
```typescript { .api }
232
interface NuxtPluginTemplate<T = Record<string, any>> extends NuxtTemplate<T> {
233
  /** Plugin execution mode */
234
  mode?: PluginMode;
235
  /** Plugin runs server-side */
236
  ssr?: boolean;
237
  /** Plugin order */
238
  order?: number;
239
}
240
```
241

242
**Usage Examples:**
243

244
```typescript
245
import { addPluginTemplate } from "@nuxt/kit";
246

247
// Dynamic plugin with configuration
248
addPluginTemplate({
249
  src: "templates/auth-plugin.mjs",
250
  filename: "auth-plugin.mjs",
251
  mode: "all",
252
  options: {
253
    providers: ["google", "github"],
254
    redirectUrl: "/dashboard"
255
  }
256
});
257

258
// Inline plugin template
259
addPluginTemplate({
260
  filename: "runtime-config-plugin.mjs",
261
  mode: "client",
262
  getContents: (options) => `
263
    export default defineNuxtPlugin(() => {
264
      const config = ${JSON.stringify(options.config)};
265
      return {
266
        provide: {
267
          config
268
        }
269
      };
270
    });
271
  `,
272
  options: {
273
    config: { apiUrl: "https://api.example.com" }
274
  }
275
});
276
```
277

278
### Template Management
279

280
Control template lifecycle and updates.
281

282
```typescript { .api }
283
/**
284
 * Trigger rebuilding Nuxt templates
285
 * @param options - Template update options
286
 * @returns Promise resolving when templates are updated
287
 */
288
function updateTemplates(
289
  options?: { filter?: (template: ResolvedNuxtTemplate<any>) => boolean }
290
): Promise<void>;
291

292
/**
293
 * Write TypeScript configuration and declarations
294
 * @param nuxt - Nuxt instance
295
 * @returns Promise resolving when types are written
296
 */
297
function writeTypes(nuxt: Nuxt): Promise<void>;
298
```
299

300
**Usage Examples:**
301

302
```typescript
303
import { updateTemplates, writeTypes } from "@nuxt/kit";
304

305
// Update all templates
306
await updateTemplates();
307

308
// Update specific templates
309
await updateTemplates({
310
  filter: (template) => template.filename.includes("api")
311
});
312

313
// Write TypeScript declarations
314
await writeTypes(nuxt);
315
```
316

317
### Advanced Template Patterns
318

319
**Conditional Templates:**
320

321
```typescript
322
import { addTemplate } from "@nuxt/kit";
323

324
export default defineNuxtModule({
325
  setup(options, nuxt) {
326
    // Only add template in development
327
    if (nuxt.options.dev) {
328
      addTemplate({
329
        filename: "dev-tools.mjs",
330
        getContents: () => `
331
          export function devLog(message) {
332
            console.log('[DEV]', message);
333
          }
334
        `
335
      });
336
    }
337
  }
338
});
339
```
340

341
**Template with External Data:**
342

343
```typescript
344
import { addTemplate } from "@nuxt/kit";
345
import { readFileSync } from "fs";
346

347
addTemplate({
348
  filename: "build-info.mjs",
349
  getContents: async () => {
350
    const packageJson = JSON.parse(readFileSync("package.json", "utf-8"));
351
    const buildTime = new Date().toISOString();
352
    
353
    return `
354
      export const buildInfo = {
355
        version: "${packageJson.version}",
356
        buildTime: "${buildTime}",
357
        environment: "${process.env.NODE_ENV}"
358
      };
359
    `;
360
  }
361
});
362
```
363

364
## Types
365

366
```typescript { .api }
367
interface NuxtServerTemplate extends NuxtTemplate {
368
  /** Template is for server-side only */
369
  island?: boolean;
370
}
371

372
interface NuxtTypeTemplate<T = Record<string, any>> extends NuxtTemplate<T> {
373
  /** Generate TypeScript declaration file */
374
  declaration?: boolean;
375
}
376
```