Next.js 16-Upgrade-Fallen: Standardwerte für parallele Routen und Middleware zum Proxying

Der größte Aufwand bei der Aktualisierung auf Next.js 16 gilt der Änderung der asynchronen Funktionen params und searchParams, da diese überall erhebliche Störungen verursachen. Zwei weniger auffällige Änderungen im Routing verdienen genauso viel Aufmerksamkeit: Parallelroute-Slots benötigen nun eine explizite Datei default.js, und die Abfangung von Anfragen wechselt von middleware.ts zu einer neuen Konvention in proxy.ts. Keine dieser Änderungen stört die Seiten, auf die man täglich klickt – genau deshalb bleiben sie oft unentdeckt. Diese Anleitung erläutert beide Änderungen, warum sie erst spät auffallen, und bietet eine Überprüfungsliste, die vor dem Veröffentlichen der Aktualisierung durchgeführt werden sollte.

Parallelroute-Slots benötigen eine default.js

Parallelwege verwenden Ordner mit dem Präfix @, um benannte Slots zu definieren, die von einem Layout nebeneinander dargestellt werden. Dashboards sind ein klassisches Beispiel: Ein Hauptinhaltsbereich neben einem dauerhaften Aktivitätsfeed oder Benachrichtigungspanel, wobei jedes seine eigene Navigationsstatus hat.

In Next.js 16 wird von jedem Slot erwartet, dass er eine Datei namens default.js enthält. Diese Datei wird von Next.js für einen Slot angezeigt, wenn die aktuelle URL keine spezifischere Übereinstimmung enthält. Fehlt diese Datei, führt eine Navigation auf eine solche Kombination zu einem 404-Fehler anstelle einer feinfühligen Umleitung. Laut den Upgrade-Hinweisen zu Next.js 16 kann der Build selbst nun abgebrochen werden, wenn ein Slot keinen Standardinhalt hat – daher sollte das genaue Verhalten für Ihre Version überprüft werden. Ein Dashboard mit einem Feed-Slot sieht so aus:

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

Der Fallback muss in der Regel nur wenig tun. Das Rendern von null verdeckt das Feld, und ein Komponenten für den leeren Zustand sorgt dafür, dass das Panel weiterhin sichtbar bleibt:

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

Warum der fehlende Standardwert erst spät sichtbar wird

Während der Entwicklung wechseln Sie meist zwischen den von Ihnen erstellten und getesteten Zuständen, wobei alle mit etwas in jedem Feld übereinstimmen. Das Problem tritt auf, wenn ein Benutzer auf eine Kombination stößt, die noch niemand ausprobiert hat: ein Deep Link, ein Neuladen einer verschachtelten URL oder eine Route, die für den Hauptinhalt vorhanden ist, aber nicht für den Feed. Ein vollständiges Seitenladen kann den vorherigen Zustand eines Feldes nicht wiederverwenden, daher benötigt Next.js default.js, um zu wissen, was rendern soll. In der Praxis bedeutet das, dass der 404-Fehler in der Produktion oft von einem verwirrten Kunden gemeldet wird, anstatt bereits in der Entwicklung erkannt zu werden. Das Hinzufügen der Datei für jedes Feld – auch dann, wenn man glaubt, sie werde niemals verwendet – ist eine günstige Absicherung.

Von middleware.ts zu proxy.ts

Die zweite Änderung betrifft die Abfangung auf Anfrageebene. Next.js 16 führt proxy.ts als neue Konvention ein für die Logik, die zuvor in middleware.ts untergebracht war, wobei der alte Dateinamen schrittweise abgeschafft wird. Zum Zeitpunkt der Erstellung beinhaltet die Migration lediglich den Umbenennung der Datei sowie der darin exportierten Funktion; der Proxy soll auf dem Node.js-Runtime laufen. Weitere Details sowie den offiziellen Codemod zur Durchführung der Umstellung finden Sie in der aktuellen Dokumentation.

Falls Ihr Middleware-Code einfach ist, verläuft der Umstieg schnell. Wenn er jedoch umfangreiche Aufgaben wie Authentifizierungsprüfungen, die Zuordnung von Benutzern zu Subdomains, Umleitungen oder das Umbenennen von Header durchführt, sollten Sie dies als Codeänderung betrachten, die einer Überprüfung bedarf, und nicht nur als Umbenennung der Datei.

Überprüfen Sie die Funktionen einzeln, nicht nur durch Umbenennung

Eine blind durchgeführte Suche und Ersetzung von middleware.ts zu proxy.ts setzt voraus, dass jede Logik unter der neuen Konvention identisch funktioniert. Stattdessen sollte man genau prüfen, was die Datei tatsächlich tut, und jede Aufgabe separat überprüfen:

• welche Anfragen von der Konfiguration des Abgleichers abgedeckt werden und ob Pfade hinzugefügt oder entfernt wurden
• wie Authentifizierungsentscheidungen getroffen werden und was passiert, wenn eine Sitzung fehlt oder abgelaufen ist
• wie Tenant-Identifikatoren aus Hostnamen oder Header extrahiert und weitergeleitet werden
• welche Umleitungen und Umbeschreibungen ausgeführt werden und in welcher Reihenfolge
• welche Header gelesen, hinzugefügt oder entfernt werden

In dieser Schicht verwandelt sich ein subtiler Verhaltensunterschied in einen Sicherheitsfehler statt in einen rein kosmetischen. Ein übersehener Einstieg im Abgleich kann dazu führen, dass eine Route unauthentifiziert bleibt; eine geänderte Header-Information kann die Trennung der Nutzer verletzen. Deshalb erfordert sie eine sorgfältige Überprüfung sowie End-to-End-Tests – nicht nur visuelle Kontrollen.

Zwei unverwandte Änderungen mit demselben Fehlermuster

Die standardmäßigen Routen und die Migration des Proxys haben technisch gesehen nichts miteinander zu tun. Teams entdecken sie oft im Rahmen derselben Upgrade-Prozesse, weil sie ein gemeinsames Muster aufweisen: Beide funktionieren in der Regel in der Entwicklung, brechen aber in bestimmten Produktionsszenarien zusammen, die schwer nachzustellen sind.

Dieses Muster lohnt es, benannt zu werden. Änderungen, die bei jedem Seitenaufruf Probleme verursachen, werden innerhalb weniger Minuten entdeckt. Die riskanten Änderungen treten nur auf ungewöhnlichen Navigationspfaden oder bei bestimmten Anfrageformen auf, weshalb ein normaler manueller Klick sie niemals auslöst. Ihr Testplan sollte gezielt diese Pfade berücksichtigen.

Auditscheckliste für den Upgrade

Bevor Sie einen Next.js 16-Upgrade als abgeschlossen deklarieren, überprüfen Sie Folgendes:

1. Jeder parallele Route-Slot verfügt über ein default.js. Suchen Sie im Verzeichnis app/ nach Ordnern, die mit @ beginnen, und überprüfen Sie jede davon.
2. Die Middleware-Logik wurde im Einklang mit den Richtlinien von proxy.ts Schritt für Schritt überprüft – sie wurde weder umbenannt noch als identisch angesehen.

Die Authentifizierung sowie die Zuordnung der Nutzer zu ihren Konten wurden nach der Migration vollständig getestet, einschließlich negativer Fälle wie fehlender Sitzungen oder unbekannter Unterdomains.

Ungewöhnliche Navigationspfade, wie tiefgehende Links, erzwungene Neuladungen von verschachtelten URLs sowie Routen, die durch einen normalen Klick niemals erreicht werden könnten, wurden absichtlich getestet, da sich dort parallele 404-Fehler verbergen können.

Warum Multi-Tenant-Dashboards das größte Risiko bergen

SaaS-Dashboards kombinieren oft beide Merkmale: parallele Routen für die verschiedenen Anzeigenbereiche sowie Middleware, die einen Unterdomain auf einen bestimmten Nutzer zuordnet, bevor eine Seite angezeigt wird. Dadurch liegt die Zuordnung der Nutzer direkt im Code, der am stärksten von dem Wechsel zum Proxy betroffen ist.

Ein Fehler hier führt selten zu offensichtlichen Problemen. Anstelle einer Fehlerrichtseite erhält man Berichte darüber, dass ein Mieter kurzzeitig die Daten eines anderen Mieters gesehen hat – was etwa so ernst ist, wie es bei einem SaaS-Produkt nur sein kann. Eine mehrschichtige Absicherung hilft: Selbst wenn der Proxy den Mieter identifiziert, sollten der Datenzugriff in Serverkomponenten sowie die Routenverarbeiter erneut die Zugehörigkeit des Mieters überprüfen, anstatt einem von oben gesetzten Header zu vertrauen. Auch das tagbasierte Caching erfordert gleiche Sorgfalt, da die Cache-Schlüssel den Mieter enthalten müssen; der Artikel zu Next.js 16 use cache und tagbasierte Revalidierung behandelt diesen Aspekt.

Häufige Fragen

Führt das Überspringen von default.js zu stillschweigenden Fehlern?

Nicht ganz. In Versionen, die diese Regel durchsetzen, erhält man einen 404-Fehler oder einen Build-Fehler – allerdings nur für die Navigationspfade, die auf den fehlenden Fallback zugreifen. Da der Fehler weit entfernt vom ursächlichen Slot auftritt, kann er leicht fälschlich als allgemeiner Routing-Fehler interpretiert werden, sofern man von dieser Änderung nichts weiß.

Kann man vorerst weiterhin middleware.ts verwenden?

Prüfen Sie die Next.js-Dokumentation für Ihre genaue Minerversion, denn die Unterstützung der alten Konvention entwickelt sich weiter. Angesichts der Tatsache, dass die Authentifizierung häufig in dieser Datei enthalten ist, ist es riskanter, die Migration endlos hinauszuzögern als die meisten anderen Upgrade-Aufgaben, und eine frühzeitige Umsetzung gibt Ihnen Zeit für eine gründliche Überprüfung.

Wie findet man schnell Slots ohne default.js?

Suchen Sie nach Verzeichnissen unter app/, deren Namen mit @ beginnen, und listen Sie jene auf, die keine Datei mit dem Namen default.js (oder default.tsx) enthalten. Ein einziger Suchvorgang über die Dateisuche Ihres Editors oder ein kurzer Shell-Befehl ermittelt alle solchen Fälle.

Zusammenfassung

Die Änderungen in Next.js 16, die am ehesten Probleme verursachen, sind nicht jene, die den normalen Ablauf stören. Parallel angelegte Route-Slots ohne Standarddatei sowie hastig umbenannte Proxy-Einträge bestehen bei oberflächlichen Tests, scheitern aber in Randfällen – manchmal mit Sicherheitsfolgen. Fügen Sie für jeden Slot eine Standarddatei hinzu, überprüfen Sie die Verantwortlichkeiten bezüglich der Abfanglogik Schritt für Schritt und planen Sie ausreichend Zeit für echte Tests der Routen, die bei einer normalen Durchsicht nie berücksichtigt werden.