1---
2name: server-routes
3description: API routes, server middleware, and Nitro server engine in Nuxt
4---
5 
6# Server Routes
7 
8Nuxt includes Nitro server engine for building full-stack applications with API routes and server middleware.
9 
10## API Routes
11 
12Create files in `server/api/` directory:
13 
14```ts
15// server/api/hello.ts
16export default defineEventHandler((event) => {
17  return { message: 'Hello World' }
18})
19```
20 
21Access at `/api/hello`.
22 
23### HTTP Methods
24 
25```ts
26// server/api/users.get.ts - GET /api/users
27export default defineEventHandler(() => {
28  return getUsers()
29})
30 
31// server/api/users.post.ts - POST /api/users
32export default defineEventHandler(async (event) => {
33  const body = await readBody(event)
34  return createUser(body)
35})
36 
37// server/api/users/[id].put.ts - PUT /api/users/:id
38export default defineEventHandler(async (event) => {
39  const id = getRouterParam(event, 'id')
40  const body = await readBody(event)
41  return updateUser(id, body)
42})
43 
44// server/api/users/[id].delete.ts - DELETE /api/users/:id
45export default defineEventHandler((event) => {
46  const id = getRouterParam(event, 'id')
47  return deleteUser(id)
48})
49```
50 
51### Route Parameters
52 
53```ts
54// server/api/posts/[id].ts
55export default defineEventHandler((event) => {
56  const id = getRouterParam(event, 'id')
57  return getPost(id)
58})
59 
60// Catch-all: server/api/[...path].ts
61export default defineEventHandler((event) => {
62  const path = getRouterParam(event, 'path')
63  return { path }
64})
65```
66 
67### Query Parameters
68 
69```ts
70// server/api/search.ts
71// GET /api/search?q=nuxt&page=1
72export default defineEventHandler((event) => {
73  const query = getQuery(event)
74  // { q: 'nuxt', page: '1' }
75  return search(query.q, Number(query.page))
76})
77```
78 
79### Request Body
80 
81```ts
82// server/api/submit.post.ts
83export default defineEventHandler(async (event) => {
84  const body = await readBody(event)
85  // Validate and process body
86  return { success: true, data: body }
87})
88```
89 
90### Headers and Cookies
91 
92```ts
93// server/api/auth.ts
94export default defineEventHandler((event) => {
95  // Read headers
96  const auth = getHeader(event, 'authorization')
97 
98  // Read cookies
99  const cookies = parseCookies(event)
100  const token = getCookie(event, 'token')
101 
102  // Set headers
103  setHeader(event, 'X-Custom-Header', 'value')
104 
105  // Set cookies
106  setCookie(event, 'token', 'new-token', {
107    httpOnly: true,
108    secure: true,
109    maxAge: 60 * 60 * 24, // 1 day
110  })
111 
112  return { authenticated: !!token }
113})
114```
115 
116## Server Middleware
117 
118Runs on every request before routes:
119 
120```ts
121// server/middleware/auth.ts
122export default defineEventHandler((event) => {
123  const token = getCookie(event, 'token')
124 
125  // Attach data to event context
126  event.context.user = token ? verifyToken(token) : null
127})
128 
129// server/middleware/log.ts
130export default defineEventHandler((event) => {
131  console.log(`${event.method} ${event.path}`)
132})
133```
134 
135Access context in routes:
136 
137```ts
138// server/api/profile.ts
139export default defineEventHandler((event) => {
140  const user = event.context.user
141  if (!user) {
142    throw createError({ statusCode: 401, message: 'Unauthorized' })
143  }
144  return user
145})
146```
147 
148## Error Handling
149 
150```ts
151// server/api/users/[id].ts
152export default defineEventHandler((event) => {
153  const id = getRouterParam(event, 'id')
154  const user = findUser(id)
155 
156  if (!user) {
157    throw createError({
158      statusCode: 404,
159      statusMessage: 'User not found',
160    })
161  }
162 
163  return user
164})
165```
166 
167## Server Utils
168 
169Auto-imported in `server/utils/`:
170 
171```ts
172// server/utils/db.ts
173export function useDb() {
174  return createDbConnection()
175}
176```
177 
178```ts
179// server/api/users.ts
180export default defineEventHandler(() => {
181  const db = useDb() // Auto-imported
182  return db.query('SELECT * FROM users')
183})
184```
185 
186## Server Plugins
187 
188Run once when server starts:
189 
190```ts
191// server/plugins/db.ts
192export default defineNitroPlugin((nitroApp) => {
193  // Initialize database connection
194  const db = createDbConnection()
195 
196  // Add to context
197  nitroApp.hooks.hook('request', (event) => {
198    event.context.db = db
199  })
200})
201```
202 
203## Streaming Responses
204 
205```ts
206// server/api/stream.ts
207export default defineEventHandler((event) => {
208  setHeader(event, 'Content-Type', 'text/event-stream')
209  setHeader(event, 'Cache-Control', 'no-cache')
210  setHeader(event, 'Connection', 'keep-alive')
211 
212  const stream = new ReadableStream({
213    async start(controller) {
214      for (let i = 0; i < 10; i++) {
215        controller.enqueue(`data: ${JSON.stringify({ count: i })}\n\n`)
216        await new Promise(r => setTimeout(r, 1000))
217      }
218      controller.close()
219    },
220  })
221 
222  return stream
223})
224```
225 
226## Server Storage
227 
228Key-value storage with multiple drivers:
229 
230```ts
231// server/api/cache.ts
232export default defineEventHandler(async (event) => {
233  const storage = useStorage()
234 
235  // Set value
236  await storage.setItem('key', { data: 'value' })
237 
238  // Get value
239  const data = await storage.getItem('key')
240 
241  return data
242})
243```
244 
245Configure storage drivers in `nuxt.config.ts`:
246 
247```ts
248export default defineNuxtConfig({
249  nitro: {
250    storage: {
251      redis: {
252        driver: 'redis',
253        url: 'redis://localhost:6379',
254      },
255    },
256  },
257})
258```
259 
260<!-- 
261Source references:
262- https://nuxt.com/docs/getting-started/server
263- https://nuxt.com/docs/directory-structure/server
264- https://nitro.build/guide
265-->
266