Pièges de la mise à niveau vers Next.js 16 : valeurs par défaut des routes parallèles et middleware pour le proxy

La majeure partie des efforts de mise à niveau vers Next.js 16 concerne la modification des objets async params et searchParams, car elle provoque des problèmes importants partout. Deux autres modifications liées au routage, moins spectaculaires, méritent tout autant d’attention : les emplacements de route parallèles nécessitent désormais un fichier default.js explicite, et l’interception des requêtes passe de middleware.ts à une nouvelle convention proxy.ts. Aucune de ces modifications ne perturbe les pages que vous consultez quotidiennement, ce qui explique précisément pourquoi elles échappent aux tests. Ce guide explique ces deux changements, les raisons pour lesquelles ils apparaissent tardivement, et fournit une liste de contrôle à effectuer avant la mise en production de la mise à niveau.

Les emplacements de route parallèles nécessitent un default.js

Les chemins parallèles utilisent des dossiers préfixés de @ pour définir des emplacements nommés que le layout affiche côte à côte. Les tableaux de bord en sont un exemple classique : une zone de contenu principale à côté d’un flux d’activités persistant ou d’un panneau de notifications, chacun ayant son propre état de navigation.

Dans Next.js 16, chaque emplacement doit disposer d’un fichier default.js. C’est ce fichier que Next.js affiche pour un emplacement lorsque l’URL actuelle ne contient aucune correspondance plus spécifique. En l’absence de ce fichier, une navigation menant à une telle combinaison renvoie un 404 au lieu de basculer proprement, et selon les notes de mise à niveau de Next.js 16, la compilation peut désormais refuser de se poursuivre si un emplacement ne possède pas de fichier par défaut ; il convient donc de vérifier le comportement exact pour votre version. Un tableau de bord avec un emplacement de flux ressemble à ceci :

app/
  dashboard/
    @feed/
      page.tsx       ← the "active" state for this slot
      default.js      ← required fallback when no more-specific match exists
    layout.tsx
    page.tsx

Le mécanisme de secours n’a généralement pas besoin de faire grand-chose. L’affichage de null cache la case correspondante, et un composant d’état vide permet au panneau de rester visible :

// app/dashboard/@feed/default.js
export default function Default() {
  return null;
}

Pourquoi le défaut manquant apparaît tardivement

Pendant le développement, on navigue principalement entre les états que l’on a créés et testés, et tous correspondent à quelque chose dans chaque case. Le problème survient lorsque l’utilisateur atteint une combinaison que personne n’a testée : un lien profond, un renouvellement de page sur une URL imbriquée, ou une route existante pour le contenu principal mais pas pour le flux d’actualités. Un chargement complet de la page ne peut pas réutiliser l’état précédent d’une case, donc Next.js a besoin de default.js pour savoir ce qu’il faut afficher. En pratique, cela signifie que l’erreur 404 est souvent signalée par un client perplexe en production plutôt que détectée pendant le développement. Ajouter ce fichier pour chaque case, même si l’on pense qu’il ne sera jamais utilisé, constitue une assurance peu coûteuse.

De middleware.ts à proxy.ts

La deuxième modification concerne l’interception au niveau des requêtes. Next.js 16 introduit proxy.ts comme nouvelle convention pour la logique qui se trouvait auparavant dans middleware.ts, et l’ancien nom de fichier est progressivement abandonné. Au moment où cet article est écrit, la migration consiste à renommer le fichier ainsi que la fonction qu’il exporte ; le proxy est conçu pour fonctionner sous le runtime Node.js. Consultez la documentation actuelle pour obtenir des détails ainsi que le codemod officiel qui gère les aspects techniques.

Si votre middleware est simple, la migration est rapide. S’il effectue des tâches importantes, telles que des vérifications d’authentification, l’identification des utilisateurs à partir de sous-domaines, des redirections ou la réécriture des en-têtes, considérez-le comme un changement de code nécessitant une revue plutôt que simplement un renommage de fichier.

Revoyez chaque fonction individuellement, et non en se contentant de renommer

Une substitution aveugle de middleware.ts vers proxy.ts suppose que chaque partie de la logique se comporte de manière identique selon la nouvelle convention. Au lieu de cela, examinez ce que fait réellement le fichier et vérifiez chaque responsabilité séparément :

• quelles requêtes sont couvertes par la configuration du comparateur, et s’il y a eu ajout ou suppression de chemins
• comment sont prises les décisions d’authentification et ce qui se passe en l’absence ou à l’expiration d’une session
• comment les identifiants des utilisateurs sont extraits des noms d’hôte ou des en-têtes et transmis à l’étape suivante
• quelles redirections et réécritures sont déclenchées, et dans quel ordre
• quels en-têtes sont lus, ajoutés ou supprimés

C’est à ce niveau que une différence subtile de comportement se transforme en vulnérabilité de sécurité plutôt qu’en simple problème esthétique. Une entrée de correspondance manquante peut laisser une route non authentifiée ; un en-tête modifié peut compromettre l’isolation des utilisateurs. C’est pourquoi elle nécessite une analyse approfondie et des tests de bout en bout, et non simplement des vérifications visuelles.

Deux modifications sans rapport présentant le même schéma d’échec

Du point de vue technique, les paramètres par défaut des routes et la migration du proxy ne sont pas liés l’un à l’autre. Les équipes ont tendance à les découvrir lors de la même mise à niveau, car elles présentent un schéma commun : toutes deux fonctionnent généralement en environnement de développement mais échouent dans des scénarios de production spécifiques difficiles à reproduire.

Ce schéma mérite d’être nommé. Les modifications qui perturbent chaque chargement de page sont détectées en quelques minutes. Les modifications à risque ne se manifestent que sur des parcours de navigation inhabituels ou des formats de requête spécifiques, de sorte qu’un clic manuel normal ne les active jamais. Votre plan de test doit viser délibérément ces parcours.

Liste de contrôle pour l’audit avant la mise à niveau

1. Chaque emplacement de route parallèle dispose d’un fichier default.js. Recherchez dans le répertoire app/ les dossiers commençant par @ et examinez chacun d’eux.
2. La logique des middleware a été revue en fonction de la convention proxy.ts, étape par étape, sans être renommée ni considérée comme identique.

L’authentification et la résolution des tenants ont été testées du début à la fin après la migration, y compris pour les cas négatifs tels qu’une session manquante ou un sous-domaine inconnu.

Des chemins de navigation inhabituels, tels que des liens profonds, des mises à jour forcées sur des URL imbriquées et des routes que un clic normal ne pourrait jamais atteindre, ont été intentionnellement testés, car c’est là que se cachent les erreurs 404 parallèles.

Pourquoi les tableaux de bord multi-tenants présentent le plus de risques

Les tableaux de bord SaaS combinent souvent ces deux fonctionnalités : des routes parallèles pour les panneaux, ainsi qu’un middleware qui associe un sous-domaine à un tenant avant que toute page ne soit affichée. Cela place la résolution des tenants directement dans le code le plus affecté par la transition du proxy.

Une erreur ici échoue rarement de manière spectaculaire. Au lieu d’une page d’erreur, on reçoit des rapports indiquant qu’un locataire a brièvement vu les données d’un autre locataire, ce qui représente à peu près le niveau de gravité maximal qu’un produit SaaS puisse connaître. Une défense en profondeur est utile : même lorsque le proxy identifie correctement le locataire, l’accès aux données dans les composants serveur et les gestionnaires de route doit vérifier à nouveau l’appartenance du locataire, plutôt que de se fier aux en-têtes fournis en amont. Le cache basé sur des étiquettes nécessite la même prudence, car les clés de cache doivent inclure l’identifiant du locataire ; l’article sur Next.js 16 : use cache et revalidation basée sur des étiquettes aborde ce sujet.

Questions fréquentes

Le fait de sauter default.js entraîne-t-il une erreur silencieuse ?

Pas complètement. Vous obtenez un code 404 ou une erreur de compilation dans les versions qui appliquent cette règle, mais uniquement pour les chemins de navigation menant au fallback manquant. Comme l’erreur apparaît loin du slot qui en est la cause, il est facile de la confondre avec une erreur de routage générale à moins de connaître ce changement.

Pouvez-vous continuer à utiliser middleware.ts pour l’instant ?

Vérifiez la documentation de Next.js correspondant à votre version mineure précise, car le support de l’ancienne convention évolue. Étant donné que l’authentification se trouve fréquemment dans ce fichier, reporter la migration indéfiniment est plus risqué que de différer la plupart des autres tâches d’upgrade, et le faire tôt vous laisse du temps pour une révision appropriée.

Comment trouver rapidement des slots sans default.js ?

Recherchez les dossiers situés sous app/ dont les noms commencent par @, puis listez ceux qui ne contiennent pas de fichier default.js (ou default.tsx). Une seule recherche dans votre éditeur ou une courte commande en shell permet de trouver tous ces cas manquants.

Conclusion

Les changements de Next.js 16 les plus susceptibles de poser des problèmes ne sont pas ceux qui perturbent le fonctionnement normal. Les emplacements de routes parallèles sans fichier par défaut, ainsi que les proxies renommés à la hâte, réussissent aux tests de base mais échouent dans des cas limites, parfois avec des conséquences sur la sécurité. Ajoutez un fichier par défaut à chaque emplacement, examinez attentivement la logique d’interception pour chaque composant, et prévoyez du temps réel pour tester les routes que les parcours habituels ne couvrent pas.