0
# Server Integration
1

2
Nitro server handler management, plugin registration, and server-side functionality integration for Nuxt applications.
3

4
## Capabilities
5

6
### Server Handler Management
7

8
Add and manage server-side request handlers for API routes and middleware.
9

10
```typescript { .api }
11
/**
12
 * Add Nitro server handler
13
 * @param handler - Server handler configuration
14
 */
15
function addServerHandler(handler: NitroEventHandler): void;
16

17
/**
18
 * Add development-only server handler
19
 * @param handler - Development server handler configuration
20
 */
21
function addDevServerHandler(handler: NitroDevEventHandler): void;
22

23
interface NitroEventHandler {
24
  /** Handler route pattern */
25
  route?: string;
26
  /** HTTP method(s) */
27
  method?: HTTPMethod | HTTPMethod[];
28
  /** Handler function file path */
29
  handler: string;
30
  /** Lazy load handler */
31
  lazy?: boolean;
32
  /** Handler middleware flag */
33
  middleware?: boolean;
34
  /** Handler metadata */
35
  meta?: HandlerMeta;
36
}
37

38
interface NitroDevEventHandler extends NitroEventHandler {
39
  /** Development environment only */
40
  dev?: boolean;
41
}
42

43
type HTTPMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
44

45
interface HandlerMeta {
46
  /** Handler name */
47
  name?: string;
48
  /** Handler description */
49
  description?: string;
50
  [key: string]: any;
51
}
52
```
53

54
**Usage Examples:**
55

56
```typescript
57
import { addServerHandler, addDevServerHandler } from "@nuxt/kit";
58

59
// Add API route handler
60
addServerHandler({
61
  route: "/api/users",
62
  handler: "~/server/api/users.get.ts"
63
});
64

65
// Add handler with specific method
66
addServerHandler({
67
  route: "/api/auth/login",
68
  method: "POST",
69
  handler: "~/server/api/auth/login.post.ts"
70
});
71

72
// Add middleware handler
73
addServerHandler({
74
  handler: "~/server/middleware/cors.ts",
75
  middleware: true
76
});
77

78
// Add lazy-loaded handler
79
addServerHandler({
80
  route: "/api/heavy-computation",
81
  handler: "~/server/api/heavy.ts",
82
  lazy: true
83
});
84

85
// Development-only handler
86
addDevServerHandler({
87
  route: "/api/dev/debug",
88
  handler: "~/server/api/debug.ts",
89
  method: "GET"
90
});
91
```
92

93
### Server Plugin System
94

95
Register server-side plugins for Nitro initialization and middleware.
96

97
```typescript { .api }
98
/**
99
 * Add Nitro server plugin
100
 * @param plugin - Plugin file path
101
 */
102
function addServerPlugin(plugin: string): void;
103
```
104

105
**Usage Examples:**
106

107
```typescript
108
import { addServerPlugin } from "@nuxt/kit";
109

110
// Add server initialization plugin
111
addServerPlugin("~/server/plugins/database.ts");
112

113
// Add authentication plugin
114
addServerPlugin("~/server/plugins/auth-setup.ts");
115

116
// Module adding server plugin
117
export default defineNuxtModule({
118
  setup() {
119
    addServerPlugin(resolve(runtimeDir, "server/plugin.mjs"));
120
  }
121
});
122
```
123

124
### Nitro Instance Access
125

126
Access the Nitro server instance for advanced server configuration.
127

128
```typescript { .api }
129
/**
130
 * Access Nitro instance (only available after 'ready' hook)
131
 * @returns Nitro server instance
132
 * @throws Error if called before Nitro is ready
133
 */
134
function useNitro(): Nitro;
135

136
interface Nitro {
137
  /** Nitro options */
138
  options: NitroOptions;
139
  /** Storage layer */
140
  storage: Storage;
141
  /** Server hooks */
142
  hooks: Hookable;
143
}
144
```
145

146
**Usage Examples:**
147

148
```typescript
149
import { useNitro } from "@nuxt/kit";
150

151
export default defineNuxtModule({
152
  setup(options, nuxt) {
153
    // Wait for Nitro to be ready
154
    nuxt.hook("ready", async () => {
155
      const nitro = useNitro();
156
      
157
      // Access Nitro configuration
158
      console.log("Nitro preset:", nitro.options.preset);
159
      
160
      // Configure storage
161
      nitro.storage.setDriver("custom", customStorageDriver);
162
      
163
      // Add Nitro hooks
164
      nitro.hooks.hook("render:response", (response) => {
165
        response.headers["X-Custom-Header"] = "value";
166
      });
167
    });
168
  }
169
});
170
```
171

172
### Prerendering Support
173

174
Configure routes for static generation and prerendering.
175

176
```typescript { .api }
177
/**
178
 * Add routes to be prerendered
179
 * @param routes - Route path(s) to prerender
180
 */
181
function addPrerenderRoutes(routes: string | string[]): void;
182
```
183

184
**Usage Examples:**
185

186
```typescript
187
import { addPrerenderRoutes } from "@nuxt/kit";
188

189
// Add static routes for prerendering
190
addPrerenderRoutes([
191
  "/about",
192
  "/contact",
193
  "/privacy-policy"
194
]);
195

196
// Dynamic route prerendering
197
export default defineNuxtModule({
198
  async setup() {
199
    // Fetch dynamic routes
200
    const posts = await fetchBlogPosts();
201
    const routes = posts.map(post => `/blog/${post.slug}`);
202
    
203
    addPrerenderRoutes(routes);
204
  }
205
});
206

207
// Conditional prerendering
208
if (process.env.PRERENDER_BLOG === "true") {
209
  addPrerenderRoutes("/blog/**");
210
}
211
```
212

213
### Server-Side Auto-Imports
214

215
Configure auto-imports specifically for server-side code.
216

217
```typescript { .api }
218
/**
219
 * Add server-side auto-imports for Nitro
220
 * @param imports - Import or array of imports to register
221
 */
222
function addServerImports(imports: Import | Import[]): void;
223

224
/**
225
 * Add directories to be scanned for server auto-imports
226
 * @param dirs - Directory path(s) to scan
227
 * @param opts - Directory scanning options
228
 */
229
function addServerImportsDir(
230
  dirs: string | string[],
231
  opts?: { prepend?: boolean }
232
): void;
233

234
/**
235
 * Add directories to be scanned by Nitro like ~/server
236
 * @param dirs - Directory path(s) to scan
237
 * @param opts - Directory scanning options
238
 */
239
function addServerScanDir(
240
  dirs: string | string[],
241
  opts?: { prepend?: boolean }
242
): void;
243
```
244

245
**Usage Examples:**
246

247
```typescript
248
import { 
249
  addServerImports, 
250
  addServerImportsDir, 
251
  addServerScanDir 
252
} from "@nuxt/kit";
253

254
// Add server utility imports
255
addServerImports([
256
  { name: "validateRequest", from: "~/server/utils/validation" },
257
  { name: "useDatabase", from: "~/server/utils/database" }
258
]);
259

260
// Add server utils directory
261
addServerImportsDir("~/server/utils");
262

263
// Add custom server directories for scanning
264
addServerScanDir([
265
  "~/server/custom-api",
266
  "~/server/custom-middleware"
267
]);
268
```
269

270
### Advanced Nitro Configuration
271

272
Configure Nitro server options and behavior through modules.
273

274
**Server Handler Patterns:**
275

276
```typescript
277
import { addServerHandler } from "@nuxt/kit";
278

279
export default defineNuxtModule({
280
  setup(options) {
281
    // RESTful API handlers
282
    addServerHandler({
283
      route: "/api/users/:id",
284
      method: "GET",
285
      handler: "~/server/api/users/[id].get.ts"
286
    });
287
    
288
    addServerHandler({
289
      route: "/api/users/:id",
290
      method: "PUT",
291
      handler: "~/server/api/users/[id].put.ts"
292
    });
293
    
294
    // Catch-all handler
295
    addServerHandler({
296
      route: "/api/proxy/**",
297
      handler: "~/server/api/proxy.ts"
298
    });
299
    
300
    // WebSocket handler (if supported)
301
    addServerHandler({
302
      route: "/api/ws",
303
      handler: "~/server/api/websocket.ts"
304
    });
305
  }
306
});
307
```
308

309
**Server Plugin Integration:**
310

311
```typescript
312
import { addServerPlugin, createResolver } from "@nuxt/kit";
313

314
export default defineNuxtModule({
315
  setup() {
316
    const resolver = createResolver(import.meta.url);
317
    
318
    // Add server initialization
319
    addServerPlugin(resolver.resolve("./runtime/server/init.mjs"));
320
    
321
    // Add database connection
322
    addServerPlugin(resolver.resolve("./runtime/server/database.mjs"));
323
  }
324
});
325
```
326

327
**Nitro Hook Integration:**
328

329
```typescript
330
export default defineNuxtModule({
331
  setup(options, nuxt) {
332
    // Configure Nitro through Nuxt hooks
333
    nuxt.hook('nitro:config', (nitroConfig) => {
334
      nitroConfig.plugins = nitroConfig.plugins || [];
335
      nitroConfig.plugins.push("~/server/plugins/custom.ts");
336
      
337
      // Add custom Nitro configuration
338
      nitroConfig.experimental = {
339
        ...nitroConfig.experimental,
340
        wasm: true
341
      };
342
    });
343
    
344
    // Add Nitro build hooks
345
    nuxt.hook('nitro:build:before', (nitro) => {
346
      console.log('Nitro build starting...');
347
    });
348
  }
349
});
350
```
351

352
**Server Storage Configuration:**
353

354
```typescript
355
export default defineNuxtModule({
356
  setup(options, nuxt) {
357
    nuxt.hook('nitro:config', (nitroConfig) => {
358
      // Configure Redis storage
359
      nitroConfig.storage = nitroConfig.storage || {};
360
      nitroConfig.storage.redis = {
361
        driver: 'redis',
362
        host: process.env.REDIS_HOST,
363
        port: process.env.REDIS_PORT,
364
        password: process.env.REDIS_PASSWORD
365
      };
366
      
367
      // Configure file system storage
368
      nitroConfig.storage.fs = {
369
        driver: 'fs',
370
        base: './data'
371
      };
372
    });
373
  }
374
});
375
```
376

377
## Types
378

379
```typescript { .api }
380
interface NitroOptions {
381
  /** Deployment preset */
382
  preset?: string;
383
  /** Server handlers */
384
  handlers?: NitroEventHandler[];
385
  /** Server plugins */
386
  plugins?: string[];
387
  /** Storage configuration */
388
  storage?: Record<string, any>;
389
  /** Experimental features */
390
  experimental?: Record<string, any>;
391
  [key: string]: any;
392
}
393

394
interface Storage {
395
  /** Set storage driver */
396
  setDriver(name: string, driver: any): void;
397
  /** Get item from storage */
398
  getItem(key: string): Promise<any>;
399
  /** Set item in storage */
400
  setItem(key: string, value: any): Promise<void>;
401
  /** Remove item from storage */
402
  removeItem(key: string): Promise<void>;
403
  [key: string]: any;
404
}
405

406
interface Hookable {
407
  /** Register hook */
408
  hook<T>(name: string, fn: T): () => void;
409
  /** Call hook */
410
  callHook<T>(name: string, ...args: any[]): Promise<T>;
411
}
412
```