A Beginner's Guide to Middleware in React Router

If you’ve ever needed to check authentication before every protected route, log requests across your application, or share data between parent and child routes in React Router, you’ve likely written the same code multiple times. React Router middleware solves this repetition problem by letting you intercept and process requests before they reach your loaders and actions.

This guide covers everything you need to implement React Router middleware in version 7.9+, from enabling the v8_middleware flag to creating your first authentication middleware with the new middleware API.

What is React Router Middleware?

React Router 7 middleware is a feature that runs code before and after your route handlers execute. Think of it as a processing pipeline where each middleware can inspect requests, add data to the context, or even short-circuit the request with a redirect.

Unlike the parallel execution of loaders in React Router 6, middleware runs sequentially in a nested chain. Parent middleware executes before child middleware on the way down, then in reverse order on the way up after generating a response.

Parent middleware → Child middleware → Route handler → Child middleware → Parent middleware

This sequential execution enables patterns that were previously impossible, like sharing authenticated user data from a parent route to all child routes without redundant database calls.

Enabling Middleware in Your Project

To start using middleware, first ensure you’re running React Router 7.9.0 or later (or 7.3.0+ with the middleware flag enabled). Then enable the feature flag in your configuration:

// react-router.config.ts
import type { Config } from "@react-router/dev/config";

export default {
  future: {
    v8_middleware: true,
  },
} satisfies Config;

This flag enables stable middleware support and the new context API. The context parameter in your loaders and actions now provides access to middleware-set data through a type-safe API.

Understanding the Context API

The new context API in React Router 7 provides a type-safe Map-like interface for sharing data between middleware and route handlers. Instead of attaching properties directly to a context object, you now use context.set() and context.get() with typed context keys:

import { createContext } from "react-router";

// Create a typed context key
const userContext = createContext<User>();

// In middleware
context.set(userContext, user);

// In loader/action
const user = context.get(userContext); // Type-safe User object

This approach eliminates TypeScript type assertions and prevents naming conflicts between different middleware.

Creating Your First Middleware

Let’s build an authentication middleware that protects routes and shares user data:

// app/middleware/auth.ts
import { redirect, createContext } from "react-router";
import type { Route } from "./+types/root";

export const userContext = createContext<User | null>();

export const authMiddleware: Route.Middleware = async ({ 
  request, 
  context,
  next
}) => {
  const user = await getUserFromSession(request);
  
  if (!user) {
    throw redirect("/login");
  }
  
  context.set(userContext, user);
  return next();
};

Apply this middleware to protected routes:

// app/routes/dashboard.tsx
import { authMiddleware, userContext } from "~/middleware/auth";

export  const  middleware: Route.MiddlewareFunction[] = [authMiddleware];

export async function loader({ context }: Route.LoaderArgs) {
  const user = context.get(userContext); // Guaranteed to exist
  const profile = await getProfile(user.id);
  return { profile };
}

The middleware runs before the loader, ensuring authenticated access and providing the user object without additional database queries.

Server Middleware vs Client Middleware

React Router supports both server and client middleware with slightly different behaviors:

Server middleware runs on the server and must return a Response:

export const middleware: Route.MiddlewareFunction[] = [
  async ({ request }, next) => {
    console.log(`Server: ${request.method} ${request.url}`);
    const response = await next();
    response.headers.set("X-Custom-Header", "value");
    return response; // Required
  };
];

Client middleware runs in the browser during client-side navigation:

export const middleware: Route.ClientMiddlewareFunction[] = [
  async ({ next }) => {
    const start = performance.now();
    await next();
    console.log(`Navigation took ${performance.now() - start}ms`);
  },
];

Common Middleware Patterns

Logging Middleware

export const loggingMiddleware: Route.Middleware = async ({ request, next }) => {
  const requestId = crypto.randomUUID();
  console.log(`[${requestId}] ${request.method} ${request.url}`);
  
  const response = await next();
  
  console.log(`[${requestId}] Response ${response.status}`);
  return response;
};

Composing Multiple Middleware

You can chain multiple middleware functions together:

// app/routes/admin.tsx
export const middleware = [
  loggingMiddleware,
  authMiddleware,
  adminRoleMiddleware
];

Each middleware executes in order, and any can short-circuit the chain by throwing a redirect or error response.

Conclusion

React Router middleware transforms how you handle cross-cutting concerns in your application. By enabling the v8_middleware flag and adopting the new context API, you can eliminate code duplication, share data efficiently between routes, and implement authentication, logging, and other patterns in a clean, reusable way.

Start with simple middleware like authentication or logging, then explore advanced patterns as your application grows. The sequential execution model and type-safe context API make middleware a powerful addition to your React Router toolkit.

FAQs

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.