`defineEventHandler()`

Defines a Nitro server route or API handler in the server/ directory.

Since Nuxt 3.0 Spec ↗

Syntax

export default defineEventHandler((event) => { ... })

Parameters

Name	Type	Required	Description
`handler`	`(event: H3Event) => any \| Promise<any>`	Yes	Function receiving the H3 event; the returned value becomes the response (objects auto-serialize to JSON).

Returns

EventHandler — A handler registered by file path under server/.

Examples

// server/api/hello.ts -> GET /api/hello
export default defineEventHandler(() => {
  return { message: 'Hello world' }
})

// server/api/users/[id].get.ts
export default defineEventHandler(async (event) => {
  const id = getRouterParam(event, 'id')
  return await db.users.findById(id)
})

// server/api/echo.post.ts
export default defineEventHandler(async (event) => {
  const body = await readBody(event)
  return { received: body }
})

Notes

Files in `server/api/` map to `/api/*`; `server/routes/` map to the root path. Method-suffixed filenames (`.get.ts`, `.post.ts`) restrict the HTTP method. Returned objects are JSON-serialized automatically. Throw `createError()` for error responses.