Middleware API Reference

Added in: astro@2.6.0

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.

Imports from astro:middleware

Section titled Imports from astro:middleware

import {
  sequence,
  createContext,
  trySerializeLocals,
  defineMiddleware,
 } from 'astro:middleware';

defineMiddleware()

Section titled defineMiddleware()

You can import and use the utility function defineMiddleware() to take advantage of type safety:

src/middleware.ts

import { defineMiddleware } from "astro:middleware";

// `context` and `next` are automatically typed
export const onRequest = defineMiddleware((context, next) => {

});

sequence()

Section titled 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()

Section titled createContext()

Type: (context: CreateContext) => APIContext

Added in: astro@2.8.0

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()

Section titled trySerializeLocals()

Type: (value: unknown) => string

Added in: astro@2.8.0

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.

Middleware exports

Section titled Middleware exports

When defining your project’s middleware in src/middleware.js, export the following user-defined functions:

onRequest()

Section titled 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();
};

Your onRequest() function will be called with the following arguments:

context

Section titled 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()

Section titled 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.