Middleware allows you to intercept requests and responses and inject behaviors dynamically every time a page or endpoint is about to be rendered.
This also allows you to set and share request-specific information across endpoints and pages by mutating a
locals object that is available in all Astro components and API endpoints
Middleware is available in both SSG and SSR Astro projects.
Basic UsageSection titled Basic Usage
src/middleware.js|ts(Alternatively, you can create
Inside this file, export an
onRequest()function. This must not be a default export.
.astrofile, access response data using
Middleware typesSection titled Middleware types
You can import and use the utility function
defineMiddleware() to take advantage of type safety:
Instead, if you’re using JsDoc to take advantage of type safety, you can use
To type the information inside
Astro.locals, which gives you autocompletion inside
.astro files and middleware code, declare a global namespace in the
Then, inside the middleware file, we can take advantage of autocompletion and type safety.
You can store any type of data inside
Astro.locals: strings, numbers, and even complex data types such as functions and maps.
Then you can use this information inside any
Example: redacting sensitive informationSection titled Example: redacting sensitive information
The example below uses middleware to replace “PRIVATE INFO” with the word “REDACTED” to allow you to render modified HTML on your page:
Chaining middlewareSection titled Chaining middleware
Multiple middlewares can be joined in a specified order using
This will result in the following console order:
API ReferenceSection titled API Reference
Section titled onRequest()
A required exported function from
src/middleware.js that will be called before rendering every page or API route. It accepts two optional arguments: context and next().
onRequest() must return a
Response: either directly, or by calling
Section titled context
An object that includes information to be made available to other middleware, API routes and
.astro routes during the rendering process.
This is an optional argument passed to
onRequest() that may contain the
locals object as well as any additional properties to be shared during rendering. For example, the
context object may include cookies used in authentication.
This is the same
context object that is passed to API routes.
Section titled next()
A function that intercepts (reads and modifies) the
Response of a
Request or calls the “next” middleware in the chain and returns a
Response. For example, this function could modify the HTML body of a response.
This is an optional argument of
onRequest(), and may provide the required
Response returned by the middleware.
Section titled locals
An object containing data from a
Response that can be manipulated inside middleware.
locals object is forwarded across the request handling process and is available as a property to
AstroGlobal. This allows data to be shared between middlewares, API routes, and
.astro pages. This is useful for storing request-specific data, such as user data, across the rendering step.
locals is an object that lives and dies within a single Astro route; when your route page is rendered,
locals won’t exist anymore and a new one will be created. Information that needs to persist across multiple page requests must be stored elsewhere.
Section titled sequence()
A function that accepts middleware functions as arguments, and will execute them in the order in which they are passed.
Section titled createContext
A low-level API to create an
APIContext, that can be used by the Astro middleware.
This function can be used by integrations/adapters to programmatically execute the Astro middleware.
Section titled trySerializeLocals
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.