Guía para Principiantes sobre Middleware en React Router

Si alguna vez has necesitado verificar la autenticación antes de cada ruta protegida, registrar solicitudes en toda tu aplicación o compartir datos entre rutas padre e hijo en React Router, probablemente hayas escrito el mismo código múltiples veces. El middleware de React Router resuelve este problema de repetición al permitirte interceptar y procesar solicitudes antes de que lleguen a tus loaders y actions.

Esta guía cubre todo lo que necesitas para implementar middleware de React Router en la versión 7.9+, desde habilitar el flag v8_middleware hasta crear tu primer middleware de autenticación con la nueva API de middleware.

¿Qué es el Middleware de React Router?

El middleware de React Router 7 es una característica que ejecuta código antes y después de que se ejecuten tus manejadores de ruta. Piensa en él como un pipeline de procesamiento donde cada middleware puede inspeccionar solicitudes, agregar datos al contexto o incluso interrumpir la solicitud con una redirección.

A diferencia de la ejecución paralela de loaders en React Router 6, el middleware se ejecuta secuencialmente en una cadena anidada. El middleware padre se ejecuta antes que el middleware hijo en el camino descendente, luego en orden inverso en el camino ascendente después de generar una respuesta.

Middleware padre → Middleware hijo → Manejador de ruta → Middleware hijo → Middleware padre

Esta ejecución secuencial habilita patrones que antes eran imposibles, como compartir datos de usuario autenticado desde una ruta padre a todas las rutas hijas sin llamadas redundantes a la base de datos.

Habilitando Middleware en tu Proyecto

Para comenzar a usar middleware, primero asegúrate de estar ejecutando React Router 7.9.0 o posterior (o 7.3.0+ con el flag de middleware habilitado). Luego habilita el feature flag en tu configuración:

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

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

Este flag habilita el soporte estable de middleware y la nueva API de contexto. El parámetro context en tus loaders y actions ahora proporciona acceso a los datos establecidos por el middleware a través de una API con seguridad de tipos.

Entendiendo la API de Contexto

La nueva API de contexto en React Router 7 proporciona una interfaz similar a Map con seguridad de tipos para compartir datos entre middleware y manejadores de ruta. En lugar de adjuntar propiedades directamente a un objeto de contexto, ahora usas context.set() y context.get() con claves de contexto tipadas:

import { createContext } from "react-router";

// Crear una clave de contexto tipada
const userContext = createContext<User>();

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

// En loader/action
const user = context.get(userContext); // Objeto User con seguridad de tipos

Este enfoque elimina las aserciones de tipo de TypeScript y previene conflictos de nombres entre diferentes middleware.

Creando tu Primer Middleware

Construyamos un middleware de autenticación que proteja rutas y comparta datos de usuario:

// 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();
};

Aplica este middleware a las rutas protegidas:

// 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); // Garantizado que existe
  const profile = await getProfile(user.id);
  return { profile };
}

El middleware se ejecuta antes del loader, asegurando el acceso autenticado y proporcionando el objeto de usuario sin consultas adicionales a la base de datos.

Middleware de Servidor vs Middleware de Cliente

React Router admite tanto middleware de servidor como de cliente con comportamientos ligeramente diferentes:

El middleware de servidor se ejecuta en el servidor y debe devolver una Response:

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

El middleware de cliente se ejecuta en el navegador durante la navegación del lado del cliente:

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

Patrones Comunes de Middleware

Middleware de Registro (Logging)

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}] Respuesta ${response.status}`);
  return response;
};

Composición de Múltiples Middleware

Puedes encadenar múltiples funciones de middleware juntas:

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

Cada middleware se ejecuta en orden, y cualquiera puede interrumpir la cadena lanzando una redirección o respuesta de error.

Conclusión

El middleware de React Router transforma la forma en que manejas preocupaciones transversales en tu aplicación. Al habilitar el flag v8_middleware y adoptar la nueva API de contexto, puedes eliminar la duplicación de código, compartir datos eficientemente entre rutas e implementar autenticación, registro y otros patrones de una manera limpia y reutilizable.

Comienza con middleware simple como autenticación o registro, luego explora patrones avanzados a medida que tu aplicación crece. El modelo de ejecución secuencial y la API de contexto con seguridad de tipos hacen del middleware una adición poderosa a tu conjunto de herramientas de React Router.

Preguntas Frecuentes

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.