Exemples de middleware Next.js, mis à jour pour proxy.ts

Exemples de middleware (proxy) Next.js

Exemples de middleware Next.js (désormais proxy.ts) : auth, géo, A/B | We.Inc

Des exemples proxy.ts fonctionnels pour Next.js 16, le fichier qui a remplacé middleware.ts : redirections d'authentification, routage par pays, cookies A/B, détection de la langue, matchers et un simulateur.

Dans Next.js 16, le fichier middleware s'appelle proxy.ts et exporte une fonction nommée proxy ; middleware.ts est déprécié et un codemod le renomme. La fonction reçoit une NextRequest et peut rediriger, réécrire, définir des en-têtes ou des cookies, ou renvoyer une réponse. Un config.matcher limite les chemins sur lesquels elle s'exécute. Elle utilise désormais le runtime Node.js par défaut.

Ce qui a changé dans Next.js 16

Avant (15 et versions antérieures)
Maintenant (16)

proxy.ts, au même niveau que app ou pages

export function middleware()
export function proxy() ou un export par défaut

Runtime Edge par défaut
Runtime Node.js par défaut ; l'option runtime lève une erreur

skipMiddlewareUrlNormalize
skipProxyUrlNormalize

Renommage manuel
npx @next/codemod@canary middleware-to-proxy .

Beaucoup de réponses en ligne décrivent encore middleware.ts sur le runtime Edge. Les exemples présentés ici utilisent le nom de fichier actuel, fonctionnent tels quels et restent assez courts pour être adaptés. Essayez le simulateur pour voir quelle branche d'un proxy combiné se déclenche pour une requête donnée avant de le déployer.

Choisissez un chemin et définissez les cookies, le pays et la langue que porte la requête fictive.
Le simulateur applique les exemples d'authentification, de pays, d'A/B et de langue présentés plus bas, dans cet ordre, dans votre navigateur.
Lisez le résultat : laisser passer, rediriger vers une nouvelle URL ou réécrire vers une route cachée.
Copiez l'exemple qui correspond à votre cas et adaptez les chemins.

Sans matcher, proxy s'exécute pour chaque requête, y compris les fichiers _next/static et les images. Excluez-les, sinon une redirection vers la connexion peut bloquer votre CSS.
Les valeurs du matcher doivent être des constantes ; la documentation précise que les variables sont ignorées car le matcher est lu au moment du build.
Gardez des vérifications optimistes dans proxy. Lisez un cookie, redirigez s'il est absent, et faites la vraie vérification des permissions au plus près de vos données.
Pour transmettre des données à la page, définissez un en-tête de requête avec NextResponse.next({ request: { headers } }). Passer les en-têtes au niveau supérieur les envoie au navigateur à la place.
L'utilitaire expérimental unstable_doesProxyMatch de next/experimental/testing/server vous permet de tester unitairement un matcher.

Questions fréquentes

Le middleware Next.js est-il déprécié ?

Le nom, oui. La version 16 déprécie la convention de fichier middleware et la renomme en proxy, avec les mêmes API de requête et de réponse. Les anciens fichiers middleware.ts sont censés migrer, et le codemod officiel renomme à la fois le fichier et la fonction exportée.

Pourquoi l'avoir renommé en proxy ?

L'équipe Next.js explique que le mot middleware était confondu avec les middlewares Express et encourageait un usage excessif. Proxy décrit une frontière réseau placée devant l'application, et l'équipe le recommande en dernier recours, quand aucune autre API ne convient.

Puis-je utiliser le runtime Edge dans proxy.ts ?

Non. Proxy utilise Node.js par défaut, et définir l'option de segment runtime dans un fichier proxy lève une erreur. Cela signifie aussi que les bibliothèques réservées à Node fonctionnent désormais à cet endroit, ce qui était une plainte fréquente au sujet de l'ancien middleware limité à Edge.

L'authentification doit-elle se faire dans proxy ?

Uniquement comme premier filtre. Le guide d'authentification de Next.js recommande de lire le cookie de session dans proxy pour des redirections rapides, puis de vérifier à nouveau la session dans une couche d'accès aux données, les Server Actions et les Route Handlers. Les Server Functions exclues par le matcher ne passent pas du tout par proxy.

Proxy fonctionne-t-il avec l'export statique ?

Non. Le tableau des plateformes dans la documentation indique que l'export statique n'est pas pris en charge, car il n'y a aucun serveur pour l'exécuter. Les serveurs Node et Docker sont pris en charge, et pour les autres hébergeurs, cela dépend de leur adaptateur.

La place de proxy dans le traitement de la requête

Next.js applique d'abord les en-têtes et redirections de next.config, puis exécute proxy, puis les réécritures beforeFiles, puis les vrais fichiers et routes. Une redirection dans next.config l'emporte donc avant même que votre code proxy ne voie la requête.
Proxy peut terminer la requête lui-même, en renvoyant une redirection ou une réponse JSON, ou la laisser continuer avec NextResponse.next() tout en ajoutant des en-têtes et des cookies au passage.

Redirection ou réécriture

Une redirection change la barre d'adresse et coûte au visiteur un aller-retour supplémentaire. Utilisez-la quand l'URL elle-même doit changer, par exemple pour envoyer les utilisateurs déconnectés vers /login.
Une réécriture sert une autre route sans changer la barre d'adresse. Elle convient aux tests A/B et aux variantes par pays, quand vous voulez que les deux versions partagent une même URL publique.

Gardez-le léger

Proxy peut s'exécuter pour les préchargements comme pour les pages vues, donc les appels à la base de données s'y multiplient vite. Lire des cookies et des en-têtes ne coûte presque rien ; interroger une table d'utilisateurs à chaque requête, si.
Les tâches de fond comme la journalisation peuvent aller dans event.waitUntil(), qui maintient l'invocation active après l'envoi de la réponse.

Motifs de matcher

Comment se comportent les chemins de config.matcher

Motif
Correspond à
Ne correspond pas à

Toutes les pages
Les routes API, les fichiers de build, le favicon

Exemples de proxy.ts

Rediriger les visiteurs non connectés

Une vérification optimiste : elle cherche seulement le cookie de session et mémorise où le visiteur voulait aller.

Routage par pays avec une réécriture

Le visiteur garde l'URL /pricing mais voit la page UE. L'en-tête de pays montré ici est celui qu'ajoute Vercel ; les autres hébergeurs utilisent leur propre nom d'en-tête.

Test A/B avec un cookie persistant

Un visiteur est affecté une seule fois à un groupe, le cookie l'y maintient, et une réécriture sert la variante à la même URL.

Envoyer les visiteurs vers leur langue

Les chemins qui commencent déjà par une langue prise en charge passent tels quels. Tout le reste est redirigé selon la première entrée Accept-Language correspondante.

Transmettre une valeur à la page via un en-tête de requête

Définir les en-têtes dans l'option request les rend lisibles avec headers() dans la route, sans les exposer au navigateur.

Exemple d'authentification : chemin protégé et aucun cookie de session.

Exemple de pays : {country} fait partie de la liste UE, donc la page UE est servie à la même URL.

Exemple A/B : le visiteur est dans le groupe {bucket}, et un cookie l'y maintient.

Exclu par le matcher de langue, donc la requête continue sans modification.

Exemple de langue : le chemin contient déjà une langue prise en charge.

Exemple de langue : la première langue prise en charge dans l'en-tête est {locale}.

Simulateur de proxy

Définissez un chemin, un cookie de session, un pays et une langue de navigateur, et voyez si les exemples ci-dessous laisseraient passer la requête, la redirigeraient ou la réécriraient.

Chemin de la requête

En-tête de pays (x-vercel-ip-country)

En-tête Accept-Language

Groupe du cookie A/B

La requête contient un cookie de session

Commencer gratuitement · Sans carte bancaire