Nuxt 4 Server Development
Server routes, API patterns, and backend development with Nitro.
Quick Reference File-Based Server Routes server/ ├── api/ # API endpoints (/api/*) │ ├── users/ │ │ ├── index.get.ts → GET /api/users │ │ ├── index.post.ts → POST /api/users │ │ ├── [id].get.ts → GET /api/users/:id │ │ ├── [id].put.ts → PUT /api/users/:id │ │ └── [id].delete.ts → DELETE /api/users/:id │ └── health.get.ts → GET /api/health ├── routes/ # Non-API routes │ └── sitemap.xml.get.ts → GET /sitemap.xml ├── middleware/ # Server middleware │ └── auth.ts # Runs on every request ├── plugins/ # Nitro plugins │ └── database.ts # Initialize database └── utils/ # Server utilities └── db.ts # Database helpers
HTTP Method Suffixes Suffix HTTP Method .get.ts GET .post.ts POST .put.ts PUT .patch.ts PATCH .delete.ts DELETE .ts All methods When to Load References
Load references/server.md when:
Implementing complex API routes Handling authentication and sessions Working with cookies and headers Building file upload endpoints Understanding Nitro internals
Load references/database-patterns.md when:
Integrating Cloudflare D1 with Drizzle Setting up PostgreSQL connections Implementing database migrations Building query patterns
Load references/websocket-patterns.md when:
Implementing real-time features Building WebSocket endpoints Using Durable Objects for state Basic Event Handler // server/api/users/index.get.ts export default defineEventHandler(async (event) => { // Return data (automatically serialized to JSON) return { users: [ { id: 1, name: 'John' }, { id: 2, name: 'Jane' } ] } })
Request Utilities URL Parameters // server/api/users/[id].get.ts export default defineEventHandler(async (event) => { const id = getRouterParam(event, 'id')
if (!id) { throw createError({ statusCode: 400, message: 'User ID is required' }) }
return { id } })
Query Parameters // GET /api/users?page=1&limit=10&search=john export default defineEventHandler(async (event) => { const query = getQuery(event)
const page = Number(query.page) || 1 const limit = Number(query.limit) || 10 const search = query.search as string | undefined
return { page, limit, search } })
Request Body // server/api/users/index.post.ts export default defineEventHandler(async (event) => { const body = await readBody(event)
// Validate body if (!body.name || !body.email) { throw createError({ statusCode: 400, message: 'Name and email are required' }) }
// Create user... return { success: true, user: { id: 1, ...body } } })
Headers export default defineEventHandler(async (event) => { // Read headers const authHeader = getHeader(event, 'authorization') const contentType = getHeader(event, 'content-type')
// Set response headers setHeader(event, 'X-Custom-Header', 'value') setHeader(event, 'Cache-Control', 'max-age=3600')
return { authHeader, contentType } })
Response Utilities Setting Status Code export default defineEventHandler(async (event) => { // Set status code setResponseStatus(event, 201) // Created
return { message: 'Resource created' } })
Redirects export default defineEventHandler(async (event) => { // Redirect return sendRedirect(event, '/new-location', 302) })
Error Handling export default defineEventHandler(async (event) => { const id = getRouterParam(event, 'id')
const user = await findUser(id)
if (!user) {
throw createError({
statusCode: 404,
statusMessage: 'Not Found',
message: User with ID ${id} not found
})
}
return user })
Cookies export default defineEventHandler(async (event) => { // Read cookie const sessionId = getCookie(event, 'session_id')
// Set cookie setCookie(event, 'session_id', 'abc123', { httpOnly: true, secure: true, sameSite: 'lax', maxAge: 60 * 60 * 24 * 7 // 1 week })
// Delete cookie deleteCookie(event, 'old_cookie')
return { sessionId } })
Server Middleware // server/middleware/auth.ts export default defineEventHandler(async (event) => { // Skip for public routes const publicRoutes = ['/api/auth/login', '/api/health'] if (publicRoutes.includes(event.path)) { return // Continue to next handler }
// Check authentication const token = getHeader(event, 'authorization')?.replace('Bearer ', '')
if (!token) { throw createError({ statusCode: 401, message: 'Authentication required' }) }
// Verify token and attach user to context const user = await verifyToken(token) event.context.user = user })
Accessing Context in Routes // server/api/profile.get.ts export default defineEventHandler(async (event) => { // User attached by middleware const user = event.context.user
if (!user) { throw createError({ statusCode: 401, message: 'Not authenticated' }) }
return { user } })
Database Integration Cloudflare D1 with Drizzle // server/utils/db.ts import { drizzle } from 'drizzle-orm/d1' import * as schema from '~/server/database/schema'
export function useDB(event: H3Event) { const { DB } = event.context.cloudflare.env return drizzle(DB, { schema }) }
// server/api/users/index.get.ts export default defineEventHandler(async (event) => { const db = useDB(event)
const users = await db.select().from(schema.users).limit(10)
return { users } })
Schema Definition // server/database/schema.ts import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core'
export const users = sqliteTable('users', { id: integer('id').primaryKey({ autoIncrement: true }), name: text('name').notNull(), email: text('email').notNull().unique(), createdAt: integer('created_at', { mode: 'timestamp' }) .notNull() .$defaultFn(() => new Date()) })
export const posts = sqliteTable('posts', { id: integer('id').primaryKey({ autoIncrement: true }), userId: integer('user_id').notNull().references(() => users.id), title: text('title').notNull(), content: text('content'), createdAt: integer('created_at', { mode: 'timestamp' }) .notNull() .$defaultFn(() => new Date()) })
CRUD Operations // server/api/users/index.post.ts import { users } from '~/server/database/schema' import { eq } from 'drizzle-orm'
export default defineEventHandler(async (event) => { const db = useDB(event) const body = await readBody(event)
// Create const [user] = await db.insert(users) .values({ name: body.name, email: body.email }) .returning()
return { user } })
// server/api/users/[id].put.ts export default defineEventHandler(async (event) => { const db = useDB(event) const id = getRouterParam(event, 'id') const body = await readBody(event)
// Update const [user] = await db.update(users) .set({ name: body.name }) .where(eq(users.id, Number(id))) .returning()
if (!user) { throw createError({ statusCode: 404, message: 'User not found' }) }
return { user } })
// server/api/users/[id].delete.ts export default defineEventHandler(async (event) => { const db = useDB(event) const id = getRouterParam(event, 'id')
// Delete await db.delete(users).where(eq(users.id, Number(id)))
return { success: true } })
Validation with Zod // server/api/users/index.post.ts import { z } from 'zod'
const createUserSchema = z.object({ name: z.string().min(2).max(100), email: z.string().email(), age: z.number().int().min(0).max(150).optional() })
export default defineEventHandler(async (event) => { const body = await readBody(event)
// Validate const result = createUserSchema.safeParse(body)
if (!result.success) { throw createError({ statusCode: 400, message: 'Validation failed', data: result.error.flatten() }) }
// Use validated data const { name, email, age } = result.data
// Create user... return { success: true } })
File Uploads // server/api/upload.post.ts export default defineEventHandler(async (event) => { const formData = await readMultipartFormData(event)
if (!formData) { throw createError({ statusCode: 400, message: 'No file uploaded' }) }
const file = formData.find(f => f.name === 'file')
if (!file) { throw createError({ statusCode: 400, message: 'File field is required' }) }
// file.filename - Original filename // file.type - MIME type // file.data - Buffer with file contents
// Upload to R2 (Cloudflare)
const { R2 } = event.context.cloudflare.env
const key = uploads/${Date.now()}-${file.filename}
await R2.put(key, file.data)
return { key, filename: file.filename, type: file.type } })
Server Utilities // server/utils/auth.ts import { H3Event } from 'h3'
export function requireAuth(event: H3Event) { const user = event.context.user
if (!user) { throw createError({ statusCode: 401, message: 'Authentication required' }) }
return user }
export function requireRole(event: H3Event, role: string) { const user = requireAuth(event)
if (user.role !== role) { throw createError({ statusCode: 403, message: 'Insufficient permissions' }) }
return user }
// Usage in routes export default defineEventHandler(async (event) => { const user = requireAuth(event) // or const admin = requireRole(event, 'admin') })
Common Anti-Patterns Missing Method Suffix // WRONG - Handles all methods // server/api/users.ts
// CORRECT - Explicit method // server/api/users.get.ts → GET // server/api/users.post.ts → POST
Not Throwing Errors // WRONG - Returns error as data export default defineEventHandler(async (event) => { const user = await findUser(id) if (!user) { return { error: 'Not found' } // 200 status! } })
// CORRECT - Throw error export default defineEventHandler(async (event) => { const user = await findUser(id) if (!user) { throw createError({ statusCode: 404, message: 'Not found' }) } })
Forgetting Async/Await // WRONG - Body not awaited export default defineEventHandler((event) => { const body = readBody(event) // Returns Promise! })
// CORRECT export default defineEventHandler(async (event) => { const body = await readBody(event) })
Troubleshooting
404 on API Routes:
Ensure file is in server/api/ (not app/api/) Check method suffix matches request (.get.ts for GET) Verify file extension is .ts
Body is Empty:
Ensure await readBody(event) not readBody(event) Check Content-Type header is set correctly For multipart, use readMultipartFormData
Middleware Not Running:
Check file is in server/middleware/ Middleware runs for ALL requests unless filtered
D1 Binding Not Found:
Check wrangler.toml has [[d1_databases]] configured Access via event.context.cloudflare.env.DB Related Skills nuxt-core: Project setup, routing, configuration nuxt-data: Composables, data fetching, state nuxt-production: Performance, testing, deployment cloudflare-d1: D1 database patterns
Version: 4.0.0 | Last Updated: 2025-12-28 | License: MIT