Guide

Event Object

Event object carries an incoming request and context.


Everytime a new HTTP requerst comes, h3 internally create an Event object and passes it though event handlers until sending response.

An event is passed through all the lifecycle hooks and composable utils to use it as context.

Example:

import { defineEventHandler, getQuery, readBody } from "h3";

app.use(defineEventHandler((event) => {
  // Log event. `.toString()` stringifies to a simple string like `[GET] /<path>`
  console.log(`Request: ${event.toString()}`);

  // Parse query parms
  const query = getQuery(event)

  // Try to read request body
  const body = await readBody(event).catch(() => {})

  // Echo back request as response
  return {
    path: event.path,
    method: event.method,
    query,
    body,
  }
}));

Properties

The main properties of an event are:

event.node

The event.node allows to access the native Node.js request and response. In runtimes other than Node.js/Bun, h3 makes a compatible shim using unjs/unenv.

Try to avoid depending on event.node.* context as much as you can and instead prefer h3 utils.
defineEventHandler((event) => {
  event.node.req; // Node.js HTTP Request
  event.node.res; // Node.js HTTP Response
});

event.web?

Only if available, it is an object with request and url propertiers to access native web request context.

event.method

Access to the normalized (uppercase) request method.

event.path

Access to the request request path. (Example: /test?test=123)

  • context with some context information about the request.
  • headers with a normalized version of the headers of the request.
  • handled with a boolean that indicates if the request has terminated.

event.headers

Access tp the normalized request Headers.

You can alternatively use getHeaders(event) or getHeader(event, name) for a simplified interface.

event.context

The context is an object that contains arbitrary information about the request. You can store your custom properies inside event.context to share across composable utils.

event.handled

Specifies if response is already handled or not. Initially for each request it is false and when a response is generated, it is set to true.

Advanced: If you manually handle the response, set it to true to tell h3 stop sending any responses.

Methods

Actually, h3 provide a function to help you to create a response before the end of the request.

event.respondWith

The respondWith method is used to create a response without ending the request.

You must craft a response using the Response constructor.

Prefer explicit return over respondWith as best practice.
A responseWith will always take precedence over the returned value, from current and next event handlers. If there is no returned value, the request will continue until the end of the stack runner.

Example:

defineEventHandler((event) => {
  await event.respondWith(new Response("Hello World"));
  return "..."; // DOES NOT WORKS
});

app.use(
  defineEventHandler((event) => {
    await event.respondWith(new Response("Hello World"));
    return "..."; // DOES NOT WORK
  }),
);

With this example, the client will receive Hello World.