🗺️ Route Middleware

[ryanflorence]

Route middleware are functions that can inspect the request before the app runs and modify the response after the app is ready to respond.

Proposal

This supersedes remix-run/react-router#9566.

Middleware are functions you can add to a middleware export of a route module:

export const middleware = [logger, redirects, session];
export const clientMiddleware = [clientLogger, clientAuth];

Middleware are called in the order they are defined in the array.

Future Flag

This feature depends on the single fetch future flag:

{
  future: {
    unstable_singleFetch: true;
    unstable_middleware: true;
  }
}

Signature

export type Middleware = {
  request: Request;
  params: Params;
  next: () => Promise<Response>;
};

function myMiddleware({
  request,
  params,
  next,
}: Middleware): Response | undefined;

Throwing Responses

Middleware can throw a response at any time. The response will be returned immediately and no other middleware will be called.

Examples

Logging Requests and Response Times

// app/logger.tsx
import { type Middleware } from "@remix-run/node";

export function logger({ request, next }: Middleware) {
  let start = Date.now();

  // wait for the app to respond
  let response = await next();

  // log the time the app took to respond
  let duration = formatDuration(Date.now() - start);
  console.log(request.method, response.status, request.url, duration);
}

This one makes sense as the first middleware in root.tsx

// app/root.tsx
import { logger } from "./logger.tsx";
export const middleware = [logger];

Require Authentication

This middleware redirects to the login page if there is no user in the session.

import { type Middleware } from "@remix-run/react";

export function requireUser({ session }: Middleware) {
  let user = session.get("user");
  if (!user) {
    session.set("returnTo", request.url);
    throw redirect("/login", 302);
  }
}

Now an entire section of your app can be protected with a single middleware:

// app/routes/dashboard.tsx
export const middleware = [requireUser];

Inspecting Responses

This example inspects the response for 404s and then checks a CMS for any redirects configured by the site admins. The redirects are checked last so that every request isn't slowed down by the CMS check.

function redirectsMiddleware({ request, next }: Middleware) {
  // attempt to handle the request
  let response = await next();

  // if it's a 404, check the CMS for a redirect, do it last
  // because it's expensive
  if (response.status === 404) {
    let cmsRedirect = await checkCMSRedirects(request.url);
    if (cmsRedirect) {
      throw redirect(cmsRedirect, 302);
    }
  }
}

React Router w/o Remix

Not sure what this looks like for React Router yet, might simply be another property on routes { middleware: [requireAuth] }

[kiliman]

export function requireUser({ session }: Middleware) {

Where is session coming from? It's not in the Middleware type.

[revskill10]

session by default makes sense. Because 100% of app needs it.

[depsimon]

Can't we add any properties to the request? The context could then live in request.context or request.whatever if the developer needs it.

[mrksbnch]

This will probably be answered in the session proposal but I assume that we can directly read the session data (that was set in a middleware) in loaders/actions? This would be needed for an auth middleware that has to deal with refresh tokens (no redirect but the new authentication token would still need to be passed down to loaders/actions).

[httpolar]

I would really rather have context objects instead of php session thing, it feels a lot more flexible

[ryanflorence]

@depsimon request is not our object, it's a built in object of the web platform, we don't really believe in monkey patching built-ins.

[huw]

Overall, my yardstick for a good middleware implementation would be one that can replace handleError for reporting errors to Sentry. So I would like to be able to define a root middleware that catches all server-side errors and ErrorResponses (anything thrown from a loader or action, anywhere in the route tree), and uses a Sentry client stored on app load / global context to send them. It would also be really valuable if I could have a middleware that automatically wraps every loader/action in a Sentry transaction; to do so I’d also like to be able to get the route name and whether it’s a loder or action.

With that in mind, this is how I would intuitively write the last example:

function redirectsMiddleware({ request, next }: Middleware) {
  // attempt to handle the request
  try {
    return response = await next();
  } catch (error) {
    if (isResponse(error) && error.status === 404) {
      // if it's a 404, check the CMS for a redirect, do it last
      // because it's expensive
      let cmsRedirect = await checkCMSRedirects(request.url);
      if (cmsRedirect) {
        throw redirect(cmsRedirect, 302);
      }
    }
  }
}

The 2 changes I made there are:

1. I would expect the middleware to return a Response—from the examples you’ve given it’s clear that I would be able to throw an error or allow a normal, unmodified response to proceed, but it’s unclear what I’m supposed to do if I want to modify a normal response. Making the semantics clear and functional would help my mental models.
2. If a loader throws, I would expect to be able to catch it. AFAIK, Remix structures ErrorResponses like this in order to reuse ordinary JavaScript semantics and I wouldn’t expect that to be any different here.

3 top-of-mind questions:

1. If I add a middleware to the root loader, is this run after every other middleware & would be able to read/modify the response sent to the user? Or would they work more like Error Boundaries, where we only run the deepest middlewares?
2. How do I add a middleware to an action? (Or: How do I add a middleware to an action but not a loader?)
3. Can middlewares read from / write to global context from 🗺️ Server Context #7644? Or can they read from AppLoadContext?

[ZeldOcarina]

Yes having a catch-all error route like Express does when you call next()in any part of the app is something I really miss a lot when working with Remix as it's hard to codify all errors and use a proper AppError object.

[ngbrown]

In conjunction with #7640, it seems like a headers param is needed to set and manipulate headers from middleware, but it is missing from the definition of the Middleware type.

[ryanflorence]

good catch, yeah that's the intent, I kinda rushed these proposals so we could get to work on them!

[ngbrown]

I realized later that the middleware could do stuff to the Response like setting headers after calling next(). But if the middleware has to catch a thrown Response then it could get messy to set headers depending on if the throw is not always converted to a Response before the next() returns (or has to be caught).

Even if the middleware's next() never throws it would still be a nice convenience to have the same headers param that the data functions have and set the headers before calling next().

[ngbrown]

If the route throws a Response (or an Error) does the next() here also throw? I.e. does the middleware have to handle that situation with a catch if it wants to do something after the next() call (either the data functions or another middleware that threw) or does it get caught before returning to each middleware on the return path and the next() resolves normally?

I think it would be simplest if the next() always resolved normally. The middleware should then check if it's an error response.

[ryanflorence]

next will not throw when app's throw, that would be a pain!

[afoures]

I am wondering, all the middleware run before loader AND action? or just loader?

[ryanflorence]

Runs before both, so you'll need to check if (request.method === "POST") return if you want to bail or whatever else you might want to do differently.

[afoures]

ok make sense, thanks

[ZeldOcarina]

Love this question and clarification, I thought it was the case but now it's certain. Thanks for asking it.

[byrichardpowell]

For Shopify Apps we have an auth method like this:

import { authenticate } from "../shopify.server";

export const loader = async ({ request }) => {
  const { sessionToken, session, admin, redirect } = await authenticate.public.checkout(
    request
  );

  const response = await admin.graphql("shop { name }", {variables})
  
  // ...etc
};

What's nice about this is:

1. Auth is simple
2. Typesafety on what's returned from authenticate.admin(request) is very easy
3. Auth can return more than anything we think can make developers lives easier, which is much than just a session. API helpers & custom redirect helpers, for example.

With Middleware, I'm imagining something like this:

import { middleware } from "../shopify.server";

export const middleware = [middleware.admin]

export const loader = async ({ context }) => {
  const {admin, sessionToken, session, redirect} = context

  const response = await admin.graphql("shop { name }", {variables})
  
  // ...etc
};

Which is really nice because auth get's even simpler, but I have 2 questions about the other points:

1. Is it correct to assume middleware can inject context into loaders/actions like this?
2. How would type safety work on Context? I assume the package would have to export a Type for the Context middleware.admin injects, and then you'd need to manually type the context value in the loader? Or is there anything more automatic we can do?

[mrksbnch]

I have a somewhat similar use-case and, from what I understood, context is set differently (see #7644). Based on some other comments here, it seems like this is where session comes into play:

export function authMiddleware({ request, session }: Middleware) {
  session.set("something", request.url);
}

export function loader({ session }: LoaderFunctionArgs) {
  let something = session.get("something");
  // ...
}

Types will then probably not be inferred automatically but via something like LoaderFunctionArgs<{ something: string }>. I guess we'll know once the session RFC was created.

[ryanflorence]

#7644 adds server context. So you'd probably authenticate the session earlier in the tree (maybe even root.tsx) and then add a context to a route right below it to get access to admin.

The reason middleware/context are separate ideas is because we want to avoid artificial async chains:

• middleware must be called in order
• context can be called in parallel

By splitting them up, contexts at the same level of the tree don't block each other, keeping responses as fast as possible.

[AlemTuzlak]

I started off writing a comment on what I would like it to look like and further I explored the other RFC's the further it cut my original comment and now I'm out of words unfortunately. This is simply amazing, also separating the context from the middleware is great. I am just want to confirm the following:

1. Middleware that is defined on a parent route runs on ALL the child routes (eg if the root loader defines middleware it runs everywhere?
2. If a parent route has middleware and a child route has middleware the flow will be: parent middleware -> child middleware -> loader -> child middleware -> parent middleware?
3. server context will be injected into every middleware for parent + child routes ( I inject db into server context on the root, I have it in every middleware + loader)?
4. would it be possible to somehow extend the context by providing methods to add more fields, eg my root gives the middleware { db } server context and there is a requireUser middleware that either redirects, or injects the user into context so that the loader gets db + user, or would that be just done with an export of server context on the child route?

[sergiodxa]

For question 4, what I understand is that middlewares can't extend context, what you could do is a mix of two contexts.

One context expose the DB connection, another context gives you User | null, then your middleware checks if the user is null and redirects.

[ryanflorence]

I think all of your assumptions are correct.

[AlemTuzlak]

I think all of your assumptions are correct.

Man that's awesome

[ryanflorence]

You used the term "middleware context" so I think the only difference is that middleware and context are independent. Later context can override or add more context, middleware can't add anything to context.

[thomasfr]

I like this middleware RFC.
A few comments/questions:

1. In the auth example, you do a redirect. There are other use cases where a middleware would require to redirect somewhere. Hardcoding the path in the middleware seems not the best idea. Is there or will there be a way to not use /login but get a Route object based on a unique keyword? Something like redirect(routes.get('LOGIN').path. Maybe a full route object which takes params as arguments to construct a url. For example: Having a route '/items/:itemId/:invoideId', this would return a valid URL: routes.get('INVOICE_DETAILS').url({itemId: 123, invoiceId: 456}). This would make it safer to reuse middlewares across projects and it would be safe to rename/restructure routes.
2. How can i distinguish between route, loader, and action requests? Since these concepts are fundamental to remix, would it make sense to have isLoaderRequest, isActionRequest, isRouteRequest (or whatever you call them) as part of the middleware function signature or part of the request object?

[AlemTuzlak]

I think you can distinguish the 2 via the method

[AlemTuzlak]

but it would maybe be cool to get the route ID if possible or info on all the routes that are currently being impacted by the middleware so you could construct a redirectTo

[thomasfr]

yes you are right, but not loader and route/document request, or? Both are GET.

[sergiodxa]

You can distinguish between a document request and a JSON request using the Sec-Fetch-Dest header, there's a function in Remix Utils to get it typed https://github.com/sergiodxa/remix-utils#sec-fetch-dest, if the value is empty the request was made by fetch, a document request has document as value.

[h3har]

can inspect the request before the app runs and modify the response after the app is ready to respond.

Is it intentional to not also allow middleware to modify requests or is this just the wrong wording.

[RichiCoder1]

With this, would it be possible to set and access route-level metadata in Middleware? It's a big of an edge case, but sometimes I wanna to toggle or affect a middleware's behavior for a specific route (for a simple example, maybe skip auth).

[AsuraKev]

True. This will be useful as if I have an auth middleware, maybe I can tag a route with skipAuth then auth middleware can skip

[jrestall]

This is great and almost exactly what I was hoping for. I've been struggling to figure out how the middleware can be used for validation and model binding though. I think if the current route matches are exposed it would be possible and make a lot of other use cases possible too, such as mentioned above by @RichiCoder1 and additional examples below.

For example, using matches, teams could simplify their action validation using their own conventions:

// validation.server.ts
async function validation(props) {
  const { request, matches, next } = props;

  const route = getTargetMatch(matches);
  if (route?.action && !route.schema)
    throw new Error("Routes with actions must have a validation schema exported.");

  if (route?.schema) {
    const result = await getValidatedFormData(request, route.schema);
    if (!result.success) throw new Response(result.errors, { status: 400 });

    // model bind the valid form data to the action 'data' prop
    props.data = result.data; // Object.assign(props, data)?
  }

  return next();
}

// routes/hello.tsx
export const middleware = [validation];

export const schema = z.object({
  a: z.number(),
  b: z.string(),
});

export function action({ data }): DataFunctionArgs<typeof schema> {
  return json({ message: "hello from action!", a: data.a, b: data.b });
}

By passing the middleware props object through to the action it allows dependency injection from middleware, this same support can be utilized by the default server context and session middleware since they inject session and context objects. Similarly routing could be turned into middleware that injects the matches object so the server runtime would just be reduced to pipeline.execute();. This could make the framework a lot more modular, flexible and default conventions could be replaced for example by adding middleware with the same name. Middleware like rewrite, rateLimiting, static could be placed before unnecessary routing and context middleware.

// middleware pipeline
exceptions -> context -> routing -> validation -> session -> resource -> loaders -> action

Adding matches could allow teams to override the default action/loader conventions to support more idiomatic rest api conventions for resource routes, or named form actions. I've had teams move to expressjs simply because they didn't want to manually check HTTP verbs in resource route actions.

// /middleware/api.server.ts
async function api({ request, matches, next }) {
  for (const match of matches) {
    if (match.route.default) continue;

    const method = request.method.toLowerCase();
    match.route.loader = (props) => match.route['get'](props); // get convention. 
    match.route.action = (props) => match.route[method](props); // post, put, patch conventions. 
  }

  return next();
}

Automatically wrapping loaders with http timing headers could be another use case:

// /middleware/timing.server.ts
async function timing({ matches, next }) {
  for (const match of matches) {
    match.route.loader = (props) => time(() => match.route.loader(props));
  }
  return next();
}

The possibilities are endless with access to matches but here's one more interesting example of a team's route config convention that wraps the default component export to make a route client only. Similar could be used for dev tooling wrapping route boundaries @AlemTuzlak.

// /middleware/config.tsx
async function config({ matches, next }) {
  for (const match of matches) {
    if(match.route.config?.clientOnly) {
      match.route.default = () => (<ClientOnly>{() => match.route.default}</ClientOnly>);
    }
  }

  return next();
}

// routes/hello.tsx
export const middleware = [config];

export const config = { clientOnly: true };

This would also require middleware to run client-side, so i'm hoping *.server.ts and *.client.ts conventions apply to middleware files.

[rubber-duck-software]

I think there should be parallel clientMiddleware to go along with Client Data. This would answer how middleware works in React Router and I think rounds out the clientLoader/clientAction feature nicely. Sometimes an app will want "global" handling of a request on the client (like handling network errors).

[jonybekov]

For handling global errors, you can use axios interceptors or wretch middlewares or something similar

[lauhon]

This looks amazing! When is it coming? 😜

[mattolson]

Super excited for this. I'm currently implementing a much more cumbersome middleware stack in server.js and would much rather have support within Remix. 👍

[dangerousdan]

Isn't the Response object read only? If the only way to modify a response is to throw, which skips all the other middleware, then it's not very middleware-like.

If I add middleware to:

1. add a X-response-time header
2. cache things

Then every time the cache hits, the response time middleware will be skipped.

I'd prefer to see an approach similar to koajs, where the request and response objects are abstracted. Then it becomes minimal effort to do things such as append a header to a response, without needing to rebuild the whole response.

It makes sense for loaders to return a Response object when there's no middleware that could potentially modify it afterwards. With middleware, it feels more logical to only construct the final Response object after all middleware.

In express, their routes directly set the HTTP response, which makes it impossible for middleware to run after a route without monkey-patching the response. The compression library (which remix-express uses) does it. Their own response-time middleware does it. The same for any express cache middleware. If remix wants to modify responses in middleware, then Response objects feels like a can of worms that'll make people write some hacky code.

Sometimes developers don't have access to or permission to use a CDN, which means they can't cache pages effectively. My ideal for Remix middleware would be to implement my own LRU-cache in middleware without having to create my own remix-run/{adapter}.

I imagine that this might be a huge breaking change, but I feel like the end result would make remix way more extensible.

[marbemac]

Would ya'll consider supporting middleware (or context, from the context RFC) in the server.entry.tsx file?

The main use case here vs the middleware in the root route, is to work with the request before the default request handler in server.entry.tsx is called. We can sort of do this today by putting together a custom server, but things like wrapping the request with AsyncLocalStorage are difficult (maybe not possible?) in dev because of how viteDevServer.ssrLoadModule('virtual:remix/server-build') works.

Here's a more concrete example of what I'd love to be able to do:

// entry.server.tsx

const storage = new AsyncLocalStorage<{ tanstackQueryClient: QueryClient }>();

function initReqCtx({ request, next }: Middleware) {
  const tanstackQueryClient = new QueryClient();

  // can access the things in storage from loaders, and in handleRequest below
  return storage.run({ tanstackQueryClient }, () => next())
}

export const middleware = [initReqCtx];

export default async function handleRequest(
  request: Request,
  responseStatusCode: number,
  responseHeaders: Headers,
  remixContext: EntryContext,
) {
  
  const stream = await renderToReadableStream(<RemixServer context={remixContext} url={request.url} />);

  const { tanstackQueryClient } = storage.getStore();
  
  /**
   * HERE! Not including the code, but here is where I pipe the stream through some transfomers
   * to inject script snippets from libraries like tanstack query, to pass their cached data to the client
   * 
   * Basically the use case is to share contextual objects with the app and loaders, and then have access
   * to those objects in the root request handler so that we can manipulate the response stream as needed.
   */

  return new Response(stream, {
    headers: responseHeaders,
    status: responseStatusCode,
  });
}

[AsuraKev]

How would this middleware play with the route loader?

[aaronadamsCA]

Having struggled mightily with session race conditions, I am really hoping single fetch + server context + route middleware will solve many of the problems described in #5647.

It seems pretty straightforward that once we enable single fetch, if we getSession() in a root route server context, we'll be able to access the same session object in all data functions. That is excellent. (We're already doing this today on Cloudflare with getLoadContext, but this new universal API is clearly better.)

What I'm less sure of is how we'll safely commitSession():

• With KV storage, I guess it would be safe to make multiple parallel commitSession() calls from multiple data functions, the only penalty maybe being unnecessary round-trips to storage?
• With cookie session storage, I think the same thing would be unsafe, because you couldn't guarantee the response would use the last cookie value?
• And so an ideal solution would be a root route middleware that calls commitSession() "on the way out"? And it's a separate API by design, since getSession() consumes load context and mutates server context, while commitSession() consumes server context and mutates response headers?

I can't decide yet whether that last part is an API smell or excellent design; but if all of the above is roughly correct, then it sounds great to me and I look forward to the improvements.

[kiliman]

I've implemented the Remix Middleware spec in user-land (no changes to Remix core). It also includes some enhancements. This currently requires Vite, and it supports HMR on middleware. It uses my Vite+Express plugin (a new version is coming out soon). Also requires Single Fetch enabled to ensure middleware works the same for both server and client navigations.

I added a couple of additional arguments to the Middleware function arguments.

export type MiddlewareFunctionArgs = {
  request: Request
  context: AppLoadContext
  params: Record<string, string>
  matches: ReturnType<typeof matchRoutes>
  next: () => Promise<Response>
}

The AppLoadContext will be included. This is a mutable context, so you can add anything you want to it and it'll be passed to all the middleware functions. Once the middleware has been called, the complete context is now available to your loaders and actions. So for example, you can have an authentication middleware that adds the current user to context.

const user = await getUser(request)
context.user = user

In addition to context, it includes the matches array. This is the return value from the matchRoutes() function in @remix-run/react.

You can have middleware functions on any route. All routes matching the current URL (same as loaders) with middleware will be called in sequence from the root to the leaf route.

You must return the Response from the next() function.

To inspect or modify the response:

const response = await next()
// do something with the status
if (response.status === '404') {
  throw redirect('/somewhere-else')
}

// you can also mutate the response (only headers for now)
response.headers.set('x-middleware', 'from middleware')

Example

// root.tsx
// export list of middleware functions
export const middleware = [root_mw1, root_mw2]

async function root_mw1({ request, context, next }: MiddlewareFunctionArgs) {
  console.log('[MIDW] root_mw1 enter')

  // add headers to the request for downstream middleware or loader/action to use
  request.headers.append('x-middleware', 'root1')
  context.root1 = 'added by root1 middleware'

  const response = await next()
  response.headers.append('x-return-middleware', 'root1 middleware')

  console.log(
    '[MIDW] root_mw1 response headers',
    Object.fromEntries(
      Array.from(response.headers).filter(([key]) => key.startsWith('x-')),
    ),
  )
  return response
}

async function root_mw2({ request, context, next }: MiddlewareFunctionArgs) {
  console.log('[MIDW] root_mw2 enter')

  request.headers.append('x-middleware', 'root2')
  context.root2 = 'added by root2 middleware'
  const response = await next()
  response.headers.append('x-return-middleware', 'root2 middleware')
  console.log(
    '[MIDW] root_mw2 response headers',
    Object.fromEntries(
      Array.from(response.headers).filter(([key]) => key.startsWith('x-')),
    ),
  )
  return response
}


// routes/counter.tsx

export const middleware = [counter_mw3]

async function counter_mw3({ request, context, next }: MiddlewareFunctionArgs) {
  console.log('[MIDW] counter_mw3 enter')
  request.headers.set('x-counter', 'counter middleware')
  context.counter = { message: 'added by counter middleware' }

  let response = await next()

  response.headers.append('x-return-middleware', 'counter middleware')
  console.log(
    '[MIDW] counter_mw3 response headers',
    Object.fromEntries(
      Array.from(response.headers).filter(([key]) => key.startsWith('x-')),
    ),
  )
  return response
}

export async function loader({ request, context }: LoaderFunctionArgs) {

  // request headers includes those added by middleware
  // context includes data appended to context

  console.log(
    '[LOADER] request header',
    Object.fromEntries(
      Array.from(request.headers).filter(([key]) => key.startsWith('x-')),
    ),
  )
  console.log('[LOADER] context', context)

  return { count: await db.getCount() }
}

Output

GET /counter 200 - - 15.922 ms

# Calling middleware chain
[INFO] calling middleware root_mw1
[MIDW] root_mw1 enter
[INFO] calling middleware root_mw2
[MIDW] root_mw2 enter
[INFO] calling middleware counter_mw3
[MIDW] counter_mw3 enter

# Finally, call Remix route handler
[INFO] calling remix handler
[LOADER] request header { 'x-counter': 'counter middleware', 'x-middleware': 'root1, root2' }
[LOADER] context {
  root1: 'added by root1 middleware',
  root2: 'added by root2 middleware',
  counter: { message: 'added by counter middleware' }
}
# Got Remix Response
[INFO] response status from remix handler 200

# Return up the middleware chain modifying headers
[MIDW] counter_mw3 response headers { 'x-return-middleware': 'counter middleware' }
[MIDW] root_mw2 response headers { 'x-return-middleware': 'counter middleware, root2 middleware' }
[MIDW] root_mw1 response headers {
  'x-return-middleware': 'counter middleware, root2 middleware, root1 middleware'
}

[ryanflorence]

Very cool! thank you

[kiliman]

I implemented middleware for a couple of reasons. One was that I really wanted to use it in my apps. But overall, I think having an actual implementation while in the RFC stage will provide meaningful feedback for the final feature.

[ryanflorence]

Note that we've added a clientMiddleware export to the route module API in this proposal to add middleware for clientLoaders and SPAs

[kiliman]

Unfortunately, I don't think I can implement clientMiddleware in user-land. It would require patching React Router.

I'm not currently using clientLoaders, so not that important to me at the moment.