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.
On all prerendered pages, the middleware runs only during the build process to create static pages and does not run in the deployed website. This applies to all pages in a
static (SSG) project. This also includes prerendered pages in
hybrid mode (default) and any pages in
server mode with
export const prerender = true.
For on-demand rendered pages in
server (default) or
export const prerender = false) mode, the middleware runs in the deployed website when the route is requested.
Basic UsageSection titled Basic Usage
src/middleware.js|ts(Alternatively, you can create
.astrofile, access response data using
The Section titled The context object
context object 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.
Storing data in Section titled Storing data in context.locals
context.locals is an object that can be manipulated inside the 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.
Integrations may set properties and provide functionality through the
locals object. If you are using an integration, check its documentation to ensure you are not overriding any of its properties or doing unnecessary work.
You can store any type of data inside
locals: strings, numbers, and even complex data types such as functions and maps.
Then you can use this information inside any
.astro file with
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.
The value of
locals cannot be overridden at run time. Doing so would risk wiping out all the information stored by the user. In
dev mode, Astro performs checks and will throw an error if
locals are overridden.
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:
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, you can take advantage of autocompletion and type safety.
Chaining middlewareSection titled Chaining middleware
Multiple middlewares can be joined in a specified order using
This will result in the following console order:Learn