Astro middleware

[matthewp]

Body

• Accepted Date: 2023-03-22
• Reference Issues/Discussions:
  • Astro middleware #469
  • Astro SSR middleware #174
  • Legacy Astro.context RFC RFC: Astro.context #230
• Implementation PR:

Summary

Introduce a middleware to Astro, where you can define code that runs on every request. This API should work regardless of the rendering mode (SSG or SSR) or adapter used. Also introduces a simple way to share request-specific data between proposed middleware, API routes, and .astro routes.

Background & Motivation

Middleware has been one of the most heavily requested feature in Astro. It's useful for handling common tasks like auth guards and setting cache headers. For me, it would make handling authentication much easier.

This proposal is heavily inspired by SvelteKit's handle hooks;

Goals

• Provide a way intercept requests and responses, allowing users to set cookies and headers
• Works both in SSR and SSG mode
• Allow users to use community-created middlewares (libraries)
  • Make available via integrations API.
• Provide an API for request-specific data
• Non-Node runtimes specific APIs. ie. Cloudflare Durable Objects.
  • Add middleware from adapter.

Non-Goals

• Route specific middleware, middlewares that are run only on specific routes

Example

A quick prototype

Middlewares can be defined in src/middleware.ts by exporting middleware (array):

export cost middleware = []

A simple middleware looks like so:

export const middleware: Middleware = async (context: APIContext, resolve: Resolve) => {
  const session = await getSession(context.request);
  const isProtectedRoute = matchRoute(context.url);
  if (!session && isProtectedRoute) {
    // early response
    return new Response(null, {
      status: 400,
    });
  }
  context.cookies.set("random-cookie", "some-value");
  const response = await resolve(context); // resolve api route or render page
  return response;
};

context is the same one provided to API route handlers. Most of Astro's request handling process will be behind resolve(), and the response object returned from middleware will be sent to the user's browser.

Multiple middleware

sequence can be imported to run multiple middlewares in sequence.

export const middleware: Middleware = sequence(
  async (context, resolve) => {
    console.log("1a");
    const response = await resolve(event);
    console.log("1b");
    return response;
  },
  async (context, resolve) => {
    console.log("2a");
    const response = await resolve(event);
    console.log("2b");
    return response;
  }
);

The log result for this example is:

1a
2a
2b
1b

locals

This proposal also adds locals property to APIContext and AsroGlobal. This locals object will be forwarded across the request handling process, allowing for 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.

export const middleware = async (context: APIContext, resolve: Resolve) => {
  context.session = await getSession(context.request);
  const response = await resolve(context);
  return response;
};

---
// pages/index.astro
const session = Astro.locals.session;
---

The value type of locals can be anything as it won't be JSON-stringified:

---
// pages/index.astro
const session = await Astro.locals.getSession();
---

locals can be typed inside src/env.d.ts (I think it's possible?):

// src/env.d.ts
// at least one of these should be possible
type Locals {}

declare namespace App {
    type Locals = {}
}

SSG mode

The middleware function will run on each route's pre-rendering step, as if it were handling a normal SSR request.

export const middleware = async (context: APIContext, resolve: Resolve) => {
  const response = await resolve(context); // pre-render step here
  return response;
};

[pilcrowonpaper]

If the middleware returned a response with a non-html body on SSG, should it ignore the path or throw an error? I think currently Astro throws an error if you try to build a page that returns a redirect response?

[ematipico]

@pilcrowonpaper

I am collecting information on different fronts around Middleware. I want to ask you about a couple of things since you are one of the people who made the proposal.

1. How would a middleware work in SSG? What's an actual use case that would fit this scenario? While you provided an example of how an API will look, we should also provide an actual use case. This is helpful to shape the API and understand if it's needed.

2. How would a middleware work in SSR? What's an actual use case that would fit this scenario? Considering that "middleware routing" is out of scope, there should be some usage that doesn't involve "sessions" or "login information."

[pilcrowonpaper]

@ematipico

Good point, for SSG (and SSR), one use can be post-processing the response html. Since this proposal also includes locals, you can define shared state in the middleware and have it accessible across routes, which would be useful both for SSR and SSG.

Considering that "middleware routing" is out of scope

I'm not sure where you got this from? By "Route specific middleware," I mean middleware that only runs on specific routes (like /some-route/*)

[ematipico]

@ematipico

Good point, for SSG (and SSR), one use can be post-processing the response html. Since this proposal also includes locals, you can define shared state in the middleware and have it accessible across routes, which would be useful both for SSR and SSG.

Thank you! Specifically, if you were a user, how would you use locals in SSG? For what and how?

Considering that "middleware routing" is out of scope

I'm not sure where you got this from? By "Route specific middleware," I mean middleware that only runs on specific routes (like /some-route/*)

Thank you for clarifying!

[matthewp]

@ematipico Another thing to think about, Vercel has a way to specific certain routes that run at the edge. Could/would we want our middleware layer to run at the edge if using the Vercel adapter? https://vercel.com/docs/build-output-api/v3#features/edge-middleware

[pilcrowonpaper]

@matthewp
Can you share state between 2 runtimes? If not, locals would not work as expected.

[pilcrowonpaper]

@ematipico

I can't think of any specific examples right now for SSG, though I'm sure there are times where you want to run the same function between routes. I just think it doesn't make sense to limit middleware to SSR and have more SSR specific features.

[ematipico]

A prototype is available here:

npm i astro@0.0.0-middleware-20230331181015

The prototype mostly follows the RFC, a small deviation:

• the middleware file will export different functions;
• the file will export onRequest function and onError function;
• onError is not used yet in the prototype
• to load the middlewares

export default defineConfig({
	middlewareOrder: ['auth', 'server']
})

• the sequence function is not exposed yet