AuraStack Router

Aura Router provides a set of lifecycle hooks that allow you to customize the behavior of your endpoints and middleware.

Aura Router supports first-class lifecycle hooks that give you fine-grained control over every phase of the request and response lifecycle.

Hooks can be defined at the router level or the endpoint level. When both define the same hook, the endpoint-level hook overrides the router-level one.

The router level only supports the onRequest, onResponse, and onError hooks. The endpoint level supports all nine hooks.

onRequest

Runs before routing. Only the raw Request is available no params, body, or matched endpoint yet.

onMatch

Runs once the request has been matched to an endpoint, before any parsing begins.

onHeaders

Runs after request headers are read, before they're validated against schemas.headers.

onParams

Runs after route params are extracted, before they're validated against schemas.params.

onSearchParams

Runs after the query string is parsed, before it's validated against schemas.searchParams.

onBody

Runs after the body is parsed, before it's validated against schemas.body.

onHandler

Runs immediately before the endpoint handler, once every field has been parsed and validated.

onResponse

Runs after the handler returns a response, before it's sent to the client.

onError

Runs when an error is thrown at any earlier phase.

Hooks

A hook is a function called at a specific phase of the request/response lifecycle. Each hook receives a context object scoped to that phase.

Lifecycle Short-Circuiting: Returning a Response (e.g., via ctx.json()) from a pre-handler hook instantly short-circuits the request pipeline—no further pre-hooks or the main handler will run. Returning non-Response values, however, may simply update the hook context and allow the pipeline to continue. Note that any Response returned from an endpoint's onResponse hook will still cascade through the router-level onResponse hook before reaching the client.

Hooks can also mutate the context object passed to them. Where a hook runs before schema validation for its field (onHeaders, onParams, onSearchParams, onBody), any mutation is applied to the value the schema then validates see the callout on each section below for what that means in practice.

Execution Order

onRequest -> onMatch -> onHeaders -> onParams -> onSearchParams -> onBody -> onHandler -> onResponse -> onError

This is the order hooks run in for a request with no errors. onError isn't a fixed final step it fires whenever an error is thrown in any of the preceding phases, and receives which phase it interrupted.

`onRequest`

onRequest runs before the request is matched to an endpoint. It's the earliest point in the lifecycle, so only the native Request object is available no params, body, headers parsing, or matched route yet.

This makes it a good fit for checks that should reject a request outright, before any routing or parsing work is spent on it: authentication, IP filtering, or global logging.

import { createEndpoint } from "@aura-stack/router/endpoint"

export const getSession = createEndpoint(
  "GET",
  "/session",
  (ctx) => {
    return ctx.json({ session: "" })
  },
  {
    hooks: {
      onRequest: ({ request, json }) => {
        if (!request.headers.has("Authorization")) {
          return json({ error: "Unauthorized" }, 401)
        }
      },
    },
  }
)

onRequest is one of three hooks also supported at the router level. Define it there to apply the same check across every endpoint, instead of repeating it per endpoint:

import { createRouter } from "@aura-stack/router"

export const router = createRouter([getSession], {
  hooks: {
    onRequest: ({ request, json }) => {
      if (!request.headers.has("Authorization")) {
        return json({ error: "Unauthorized" }, 401)
      }
    },
  },
})

`onMatch`

onMatch runs once the request has been matched to an endpoint, before any parsing has started. At this point you know which endpoint will handle the request, but nothing about its params, headers, or body yet.

Useful for per-route metrics or feature-flag checks tied to a specific endpoint.

This hook isn't available at the router level, because the router doesn't yet know which endpoint will match when the request first arrives. It can only be defined at the endpoint level.

import { createEndpoint } from "@aura-stack/router/endpoint"

export const getSession = createEndpoint(
  "GET",
  "/session",
  (ctx) => {
    return ctx.json({ session: "" })
  },
  {
    hooks: {
      onMatch: () => {
        console.log("Request matched to endpoint")
      },
    },
  }
)

`onHeaders`

onHeaders runs once the incoming request headers have been read, before they're validated against schemas.headers (if defined). The hook receives the same HeadersBuilder used to construct the response, so it's also a convenient place to set response headers or cookies that should apply no matter how the request is later handled e.g. a version header on every response.