API Reference

Middleware (astro:middleware)

Added In:

Middleware allows you to intercept requests and responses and inject behaviors dynamically every time a page or endpoint is about to be rendered. For features and usage examples, see our middleware guide.

onRequest()

Type: (context: APIContext, next: MiddlewareNext) => Promise<Response> | Response | Promise<void> | void

A required exported function from src/middleware.js that will be called before rendering every page or API route. It receives two arguments: context and next(). onRequest() must return a Response: either directly, or by calling next().

src/middleware.js

export function onRequest (context, next) {
    // intercept response data from a request
    // optionally, transform the response
    // return a Response directly, or the result of calling `next()`
    return next();
};

context

Type: APIContext

The first argument of onRequest() is a context object. It mirrors many of the Astro global properties.

See Endpoint contexts for more information about the context object.

next()

Type: (rewritePayload?: string | URL | Request) => Promise<Response>

The second argument of onRequest() is a function that calls all the subsequent middleware in the chain and returns a Response. For example, other middleware could modify the HTML body of a response and awaiting the result of next() would allow your middleware to respond to those changes.

Since Astro v4.13.0, next() accepts an optional URL path parameter in the form of a string, URL, or Request to rewrite the current request without retriggering a new rendering phase.

sequence()

Type: (...handlers: MiddlewareHandler[]) => MiddlewareHandler

A function that accepts middleware functions as arguments, and will execute them in the order in which they are passed.

src/middleware.js

import { sequence } from "astro:middleware";

async function validation(_, next) {...}
async function auth(_, next) {...}
async function greeting(_, next) {...}

export const onRequest = sequence(validation, auth, greeting);

createContext()

Type: (context: CreateContext) => APIContext

Added In:

A low-level API to create an APIContextto be passed to an Astro middleware onRequest() function.

This function can be used by integrations/adapters to programmatically execute the Astro middleware.

trySerializeLocals()

Type: (value: unknown) => string

Added In:

A low-level API that takes in any value and tries to return a serialized version (a string) of it. If the value cannot be serialized, the function will throw a runtime error.