h3 Utilities

h3 is the lightweight HTTP toolkit that powers Nitro, shipping dozens of helpers for handling requests and responses with minimal boilerplate.

4 min read Level 3/5 #nuxt#h3#server

What you'll learn

Read input with getQuery, readBody, and getHeader
Shape responses with setResponseStatus, sendRedirect, and setHeader
Throw HTTP errors with createError

h3 is the HTTP framework underneath Nitro — a tiny abstraction over Node, Bun, Deno, and Workers. Its helpers are auto-imported in every server file.

Reading Requests

// server/api/echo.post.ts
export default defineEventHandler(async (event) => {
  const query = getQuery(event)               // { q?: string }
  const body = await readBody(event)          // any
  const ua = getHeader(event, 'user-agent')   // string | undefined
  const ip = getRequestIP(event, { xForwardedFor: true })

  return { query, body, ua, ip }
})

For URL params on dynamic routes, getRouterParam(event, 'name') returns the value from the filename bracket.

Shaping Responses

export default defineEventHandler((event) => {
  setResponseStatus(event, 201)
  setHeader(event, 'Cache-Control', 'no-store')
  return { created: true }
})

Redirects

export default defineEventHandler((event) => {
  return sendRedirect(event, '/login', 302)
})

Errors With `createError`

export default defineEventHandler((event) => {
  const id = getRouterParam(event, 'id')
  if (!id) {
    throw createError({
      statusCode: 400,
      statusMessage: 'Bad Request',
      data: { reason: 'missing id' },
    })
  }
})

The thrown error becomes a JSON response with the right status code. data is attached for the client.

Other Useful Helpers

getCookie / setCookie / deleteCookie
readMultipartFormData — multipart uploads
proxyRequest — pass-through to another upstream
sendNoContent — quick 204 response
assertMethod(event, 'POST') — guard methods
useStorage('cache').setItem(...) — Nitro’s built-in key-value cache

When in doubt, the h3 docs list everything alphabetically.

Custom Server Handlers →