1# Nuxt Server Patterns
2 
3> **Versions:** Nuxt uses h3 v1 and nitropack v2. Patterns from h3 v2 or nitro v3 docs won't work.
4 
5## When to Use
6 
7Working with `server/` directory - API routes, server middleware, server utilities.
8 
9## Server Directory Structure
10 
11```
12server/
13├── api/                    # API endpoints
14│   ├── users.get.ts        # GET /api/users
15│   ├── users.post.ts       # POST /api/users
16│   └── users/
17│       └── [id].get.ts     # GET /api/users/:id
18├── routes/                 # Non-API routes
19│   └── healthz.get.ts      # GET /healthz
20├── middleware/             # Server middleware
21│   └── log.ts
22└── utils/                  # Server utilities (auto-imported)
23    └── db.ts
24```
25 
26## API Routes
27 
28File naming determines HTTP method and route:
29 
30- `users.get.ts` → GET /api/users
31- `users.post.ts` → POST /api/users
32- `users/[userId].get.ts` → GET /api/users/:userId
33- `users/[userId].delete.ts` → DELETE /api/users/:userId
34 
35**REQUIRED: Use descriptive param names:** `[userId].get.ts` NOT `[id].get.ts`
36 
37## Red Flags - Stop and Check Skill
38 
39If you're thinking any of these, STOP and re-read this skill:
40 
41- "I'll use event.context.params like before"
42- "Generic [id] is fine for params"
43- "Don't need .get.ts suffix"
44- "I remember how Nuxt 3 API routes worked"
45 
46All of these mean: You're using outdated patterns. Use Nuxt 4 patterns instead.
47 
48### Basic API Route
49 
50```ts
51// server/api/users.get.ts
52export default defineEventHandler(async (event) => {
53  const users = await fetchUsers()
54  return users
55})
56```
57 
58### Route with Params
59 
60```ts
61// server/api/users/[userId].get.ts
62export default defineEventHandler(async (event) => {
63  const userId = getRouterParam(event, 'userId')
64 
65  if (!userId) {
66    throw createError({
67      statusCode: 400,
68      message: 'User ID is required'
69    })
70  }
71 
72  const user = await fetchUserById(userId)
73 
74  if (!user) {
75    throw createError({
76      statusCode: 404,
77      message: 'User not found'
78    })
79  }
80 
81  return user
82})
83```
84 
85### Route with Query Params
86 
87```ts
88// server/api/users.get.ts
89export default defineEventHandler(async (event) => {
90  const query = getQuery(event)
91  const page = Number(query.page) || 1
92  const limit = Number(query.limit) || 10
93 
94  const users = await fetchUsers({ page, limit })
95  return users
96})
97```
98 
99### Route with Body
100 
101```ts
102// server/api/users.post.ts
103export default defineEventHandler(async (event) => {
104  const body = await readBody(event)
105 
106  // Validate body
107  if (!body.name || !body.email) {
108    throw createError({
109      statusCode: 400,
110      message: 'Missing required fields: name, email'
111    })
112  }
113 
114  const user = await createUser(body)
115  setResponseStatus(event, 201)
116  return user
117})
118```
119 
120### Validation with Valibot
121 
122Use `readValidatedBody` and `getValidatedQuery` for schema validation:
123 
124```ts
125// server/api/users.post.ts
126import * as v from 'valibot'
127 
128const UserSchema = v.object({
129  name: v.pipe(v.string(), v.minLength(1)),
130  email: v.pipe(v.string(), v.email())
131})
132 
133export default defineEventHandler(async (event) => {
134  const body = await readValidatedBody(event, v.parser(UserSchema))
135  // body is typed as { name: string, email: string }
136  const user = await createUser(body)
137  setResponseStatus(event, 201)
138  return user
139})
140```
141 
142```ts
143// server/api/users.get.ts
144import * as v from 'valibot'
145 
146const QuerySchema = v.object({
147  page: v.optional(v.pipe(v.string(), v.transform(Number)), '1'),
148  limit: v.optional(v.pipe(v.string(), v.transform(Number)), '10')
149})
150 
151export default defineEventHandler(async (event) => {
152  const { page, limit } = await getValidatedQuery(event, v.parser(QuerySchema))
153  return fetchUsers({ page, limit })
154})
155```
156 
157## Error Handling
158 
159Use `createError` for HTTP errors:
160 
161```ts
162throw createError({
163  statusCode: 400,
164  statusMessage: 'Bad Request',
165  message: 'Invalid input',
166  data: { field: 'email' } // Optional additional data
167})
168```
169 
170## Server Middleware
171 
172Runs on every server request:
173 
174```ts
175// server/middleware/log.ts
176export default defineEventHandler((event) => {
177  console.log(`${event.method} ${event.path}`)
178})
179```
180 
181Named middleware for specific patterns:
182 
183```ts
184// server/middleware/auth.ts
185export default defineEventHandler((event) => {
186  const token = getRequestHeader(event, 'authorization')
187 
188  if (!token) {
189    throw createError({
190      statusCode: 401,
191      message: 'Unauthorized'
192    })
193  }
194 
195  // Attach user to event context
196  event.context.user = await verifyToken(token)
197})
198```
199 
200## Server Utils
201 
202Reusable server functions (auto-imported):
203 
204```ts
205// server/utils/db.ts
206import { db } from './database'
207 
208export async function fetchUsers(options: { page: number, limit: number }) {
209  return await db.select().from('users').limit(options.limit).offset((options.page - 1) * options.limit)
210}
211 
212export async function fetchUserById(id: string) {
213  return await db.select().from('users').where({ id }).first()
214}
215```
216 
217Auto-imported in all server routes and middleware.
218 
219**Import server utils from client (Nuxt 4.3+):**
220 
221```ts
222// Use #server alias for type-safe server-only imports
223import type { User } from '#server/utils/db'
224```
225 
226**Note:** Only types are imported; actual server code never bundles into client.
227 
228## Cached Functions
229 
230Use `defineCachedFunction` for caching expensive operations in server utils:
231 
232```ts
233// server/utils/github.ts
234export const fetchRepo = defineCachedFunction(
235  async (owner: string, repo: string) => {
236    return await $fetch(`https://api.github.com/repos/${owner}/${repo}`)
237  },
238  {
239    maxAge: 60 * 5,  // Cache for 5 minutes
240    swr: true,       // Stale-while-revalidate
241    name: 'github-repo',
242    getKey: (owner, repo) => `${owner}/${repo}`,
243  }
244)
245```
246 
247## Cached Event Handlers
248 
249Use `defineCachedEventHandler` for ISR-style caching on API routes:
250 
251```ts
252// server/api/products/[productId].get.ts
253export default defineCachedEventHandler(
254  async (event) => {
255    const productId = getRouterParam(event, 'productId')
256    return await fetchProductById(productId)
257  },
258  {
259    maxAge: 3600,  // Cache for 1 hour
260    swr: true,     // Serve stale while revalidating
261    getKey: event => getRouterParam(event, 'productId') ?? '',
262  }
263)
264```
265 
266## Generic Error Handler
267 
268Centralize error handling for H3 errors, validation errors, and fallbacks:
269 
270```ts
271// server/utils/error-handler.ts
272import { isError, createError } from 'h3'
273import * as v from 'valibot'
274 
275export function handleApiError(error: unknown, fallback: { statusCode?: number, message: string }): never {
276  // Re-throw existing H3 errors
277  if (isError(error)) throw error
278 
279  // Handle Valibot validation errors
280  if (v.isValiError(error)) {
281    throw createError({ statusCode: 400, message: error.issues[0].message })
282  }
283 
284  // Generic fallback
285  throw createError({ statusCode: fallback.statusCode ?? 502, message: fallback.message })
286}
287```
288 
289Usage in routes:
290 
291```ts
292export default defineEventHandler(async (event) => {
293  try {
294    const data = await fetchExternalApi()
295    return data
296  } catch (error) {
297    handleApiError(error, { statusCode: 502, message: 'Failed to fetch data' })
298  }
299})
300```
301 
302## Request Helpers
303 
304```ts
305// Get params
306const userId = getRouterParam(event, 'userId')
307 
308// Get query
309const query = getQuery(event)
310 
311// Get body
312const body = await readBody(event)
313 
314// Get headers
315const auth = getRequestHeader(event, 'authorization')
316 
317// Get cookies
318const token = getCookie(event, 'token')
319 
320// Get method
321const method = getMethod(event)
322 
323// Get IP
324const ip = getRequestIP(event)
325```
326 
327## Response Helpers
328 
329```ts
330// Set status code
331setResponseStatus(event, 201)
332 
333// Set headers
334setResponseHeader(event, 'X-Custom', 'value')
335setResponseHeaders(event, { 'X-Custom': 'value', 'X-Another': 'value' })
336 
337// Set cookies
338setCookie(event, 'token', 'value', {
339  httpOnly: true,
340  secure: true,
341  sameSite: 'lax',
342  maxAge: 60 * 60 * 24 * 7 // 1 week
343})
344 
345// Redirect
346return sendRedirect(event, '/login', 302)
347 
348// Stream
349return sendStream(event, stream)
350 
351// No content
352return sendNoContent(event)
353```
354 
355## Background Tasks
356 
357Use `event.waitUntil()` for async tasks that shouldn't block the response (Nuxt 4+):
358 
359```ts
360// server/api/analytics.post.ts
361export default defineEventHandler(async (event) => {
362  const data = await readBody(event)
363 
364  // Don't block response with analytics logging
365  event.waitUntil(
366    logAnalytics(data)
367  )
368 
369  return { success: true }
370})
371```
372 
373**Use cases:** logging, caching, background processing, async cleanup.
374 
375## Best Practices
376 
377- **Use descriptive param names** - `[userId]` not `[id]`
378- **Keep routes thin** - delegate to server utils
379- **Validate input** at route level
380- **Use typed errors** with createError
381- **Handle errors gracefully** - don't expose internals
382- **Use server utils** for DB/external APIs
383- **Don't expose sensitive data** in responses
384- **Set proper status codes** - 201 for created, 204 for no content
385- **Use event.waitUntil()** for background tasks that shouldn't block responses
386 
387## Common Mistakes
388 
389| ❌ Wrong                  | ✅ Right                      |
390| ------------------------- | ----------------------------- |
391| `event.context.params.id` | `getRouterParam(event, 'id')` |
392| `return res.json(data)`   | `return data`                 |
393| `[id].get.ts`             | `[userId].get.ts`             |
394| `users-id.get.ts`         | `users/[id].get.ts`           |
395| Throw generic errors      | Use createError with status   |
396 
397## WebSocket
398 
399```ts
400// server/routes/_ws.ts
401export default defineWebSocketHandler({
402  open(peer) {
403    console.log('Client connected:', peer.id)
404  },
405  message(peer, message) {
406    peer.send(`Echo: ${message.text()}`)
407    // Broadcast to all: peer.publish('channel', message)
408  },
409  close(peer) {
410    console.log('Client disconnected:', peer.id)
411  }
412})
413```
414 
415Enable in config:
416 
417```ts
418// nuxt.config.ts
419export default defineNuxtConfig({
420  nitro: {
421    experimental: { websocket: true }
422  }
423})
424```
425 
426## Server-Sent Events (Experimental)
427 
428```ts
429// server/api/stream.get.ts
430export default defineEventHandler(async (event) => {
431  const stream = createEventStream(event)
432 
433  const interval = setInterval(async () => {
434    await stream.push({ data: JSON.stringify({ time: Date.now() }) })
435  }, 1000)
436 
437  stream.onClosed(() => {
438    clearInterval(interval)
439  })
440 
441  return stream.send()
442})
443```
444 
445## Resources
446 
447- Nuxt server: https://nuxt.com/docs/guide/directory-structure/server
448- h3 (Nitro engine): https://v1.h3.dev/
449- Nitro: https://nitro.build/
450 
451> **For database/storage APIs:** see `nuxthub` skill
452