Guide du débutant sur les Middleware dans React Router

Si vous avez déjà eu besoin de vérifier l’authentification avant chaque route protégée, d’enregistrer les requêtes dans toute votre application, ou de partager des données entre les routes parentes et enfants dans React Router, vous avez probablement écrit le même code plusieurs fois. Les middleware React Router résolvent ce problème de répétition en vous permettant d’intercepter et de traiter les requêtes avant qu’elles n’atteignent vos loaders et actions.

Ce guide couvre tout ce dont vous avez besoin pour implémenter les middleware React Router dans la version 7.9+, de l’activation du flag v8_middleware à la création de votre premier middleware d’authentification avec la nouvelle API middleware.

Qu’est-ce qu’un Middleware React Router ?

Un middleware React Router 7 est une fonctionnalité qui exécute du code avant et après l’exécution de vos gestionnaires de route. Considérez-le comme un pipeline de traitement où chaque middleware peut inspecter les requêtes, ajouter des données au contexte, ou même court-circuiter la requête avec une redirection.

Contrairement à l’exécution parallèle des loaders dans React Router 6, les middleware s’exécutent séquentiellement dans une chaîne imbriquée. Le middleware parent s’exécute avant le middleware enfant à la descente, puis dans l’ordre inverse à la remontée après la génération d’une réponse.

Middleware parent → Middleware enfant → Gestionnaire de route → Middleware enfant → Middleware parent

Cette exécution séquentielle permet des patterns qui étaient auparavant impossibles, comme le partage de données utilisateur authentifiées d’une route parente vers toutes les routes enfants sans appels redondants à la base de données.

Activer les Middleware dans votre projet

Pour commencer à utiliser les middleware, assurez-vous d’abord d’exécuter React Router 7.9.0 ou une version ultérieure (ou 7.3.0+ avec le flag middleware activé). Ensuite, activez le feature flag dans votre configuration :

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

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

Ce flag active la prise en charge stable des middleware et la nouvelle API de contexte. Le paramètre context dans vos loaders et actions fournit désormais l’accès aux données définies par les middleware via une API type-safe.

Comprendre l’API de contexte

La nouvelle API de contexte dans React Router 7 fournit une interface type-safe similaire à Map pour partager des données entre les middleware et les gestionnaires de route. Au lieu d’attacher des propriétés directement à un objet de contexte, vous utilisez maintenant context.set() et context.get() avec des clés de contexte typées :

import { createContext } from "react-router";

// Créer une clé de contexte typée
const userContext = createContext<User>();

// Dans le middleware
context.set(userContext, user);

// Dans le loader/action
const user = context.get(userContext); // Objet User type-safe

Cette approche élimine les assertions de type TypeScript et prévient les conflits de nommage entre différents middleware.

Créer votre premier Middleware

Construisons un middleware d’authentification qui protège les routes et partage les données utilisateur :

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

Appliquez ce middleware aux routes protégées :

// 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); // Garanti d'exister
  const profile = await getProfile(user.id);
  return { profile };
}

Le middleware s’exécute avant le loader, garantissant un accès authentifié et fournissant l’objet utilisateur sans requêtes supplémentaires à la base de données.

Middleware côté serveur vs Middleware côté client

React Router prend en charge à la fois les middleware côté serveur et côté client avec des comportements légèrement différents :

Les middleware côté serveur s’exécutent sur le serveur et doivent retourner une Response :

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

Les middleware côté client s’exécutent dans le navigateur lors de la navigation côté client :

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

Patterns courants de Middleware

Middleware de journalisation

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

Composer plusieurs Middleware

Vous pouvez enchaîner plusieurs fonctions middleware ensemble :

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

Chaque middleware s’exécute dans l’ordre, et n’importe lequel peut court-circuiter la chaîne en lançant une redirection ou une réponse d’erreur.

Conclusion

Les middleware React Router transforment la façon dont vous gérez les préoccupations transversales dans votre application. En activant le flag v8_middleware et en adoptant la nouvelle API de contexte, vous pouvez éliminer la duplication de code, partager efficacement les données entre les routes, et implémenter l’authentification, la journalisation et d’autres patterns de manière propre et réutilisable.

Commencez par des middleware simples comme l’authentification ou la journalisation, puis explorez des patterns avancés au fur et à mesure que votre application grandit. Le modèle d’exécution séquentielle et l’API de contexte type-safe font des middleware un ajout puissant à votre boîte à outils React Router.

FAQ

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.