Next.js Migration & Rettung

Zwei Situationen führen die meisten Teams hierher. Entweder ist eine bestehende Next.js-Anwendung dem Pages Router entwachsen und der inkrementelle Weg ist nicht offensichtlich - oder eine von jemand anderem gebaute Anwendung ist zu etwas geworden, das das aktuelle Team nicht mehr zu deployen wagt.

Beides ist lösbar. Keines erfordert einen Rewrite.

Pages Router zu App Router

Die beiden Router arbeiten zusammen. Das ist die gesamte Strategie: eine gemeinsame Anwendung, in der app/ und pages/ koexistieren, migriert von den Blättern her, wobei jede Route hinter ihrem eigenen Pull Request und ihrer eigenen Verifikation umzieht.

Wir beginnen bei Routen mit wenig Traffic und geringem Risiko, um die gemeinsamen Muster aufzubauen - Layouts, Datenzugriff, Error Boundaries - und arbeiten uns dann zu den Routen vor, auf die es ankommt. Datenabrufe wandern aus getServerSideProps in den Komponentenbaum. Client-State, der nur existiert hat, um das alte Rendering-Modell auszugleichen, verschwindet meist ganz.

Die Reihenfolge ist bewusst gewählt, nicht alphabetisch. Zuerst ziehen die Routen um, die dem Team die neuen Muster zum geringsten Preis des Irrtums beibringen, zuletzt die, bei denen ein Irrtum teuer ist. Wenn ein Checkout oder ein Dashboard umzieht, sind die Konventionen, die es braucht, bereits an etwas erprobt worden, das keinen Umsatz trägt.

Am längsten dauert meist nicht das Routing. Es ist der geteilte Code, der das alte Modell vorausgesetzt hat - ein Data-Hook, der im Browser laufen wollte, ein Context Provider um die gesamte Anwendung, weil eine Komponente drei Ebenen tiefer einen Wert brauchte, eine Authentifizierungsprüfung, die für getServerSideProps geschrieben wurde. Jedes davon hat im neuen Modell eine kleinere Entsprechung, und sie zu finden ist die eigentliche Arbeit. Die Mechanik im Detail.

Ein anderes Framework zu Next.js

Create React App, Vite-SPAs, Gatsby und ein langer Schwanz maßgeschneiderter Webpack-Konfigurationen. Der mechanische Teil sind Routing und Build-Konfiguration; der Teil, der Urteilsvermögen braucht, ist die Entscheidung, welche Annahmen der Anwendung Framework-Artefakte waren und welche echte Anforderungen.

Eine Single-Page-Anwendung, die auf Server-Rendering umzieht, ist der Fall mit den meisten Überraschungen, weil in einer SPA alles einen Browser voraussetzen darf. window im Modulrumpf, ein in Ortszeit formatiertes Datum, ein clientseitiger Auth-Guard, der das Einzige war, was den Zugriff auf eine Seite verhindert hat - alles funktioniert einwandfrei, bis derselbe Code auf einem Server läuft. Diese Migration hat eine eigene Seite, weil sie genug Arbeit für ein eigenes Projekt ist.

Geerbte Codebasen

Bevor wir etwas ändern, lesen wir alles. Zwei Wochen Orientierung ergeben eine Abhängigkeitskarte, ein Rendering-Inventar jeder Route, eine Liste dessen, was tot ist, und ein priorisiertes Risikoregister. Dieses Dokument gehört Ihnen, unabhängig davon, wie Sie sich danach entscheiden - es ist das, was die Codebasis wieder steuerbar macht, und mehrere Kunden haben es intern übernommen und die Arbeit selbst erledigt.

Wir halten das für ein vernünftiges Ergebnis.

Das Risikoregister ist der Teil, der Gespräche verändert. „Die Codebasis ist ein Chaos" ist ein Gefühl und lässt sich nicht einplanen. „Vier Routen haben keine Error Boundary, die Zahlungsanbindung hat keinen Test, und zwei Abhängigkeiten haben bekannte Advisories ohne Upgrade-Pfad" ist eine Liste, und eine Liste lässt sich nach Priorität abarbeiten, von wem auch immer gerade Zeit hat. Was diese Bestandsaufnahme ergibt.

Was die Migration zusammenhält

URLs ziehen nicht um. Die Migration ist intern. Jede Adresse, die gestern gerankt hat, antwortet morgen gleich - und wo eine sich wirklich ändern muss, leitet sie dauerhaft weiter, und die Weiterleitung wird in der CI geprüft.

Jeder Schritt ist deploybar. Kein langlebiger Migrationsbranch. Wenn die Arbeit ein Quartal pausiert, weil Ihre Prioritäten sich geändert haben, ist das Gemergte in sich stimmig und der Rest eine Liste statt eines Konflikts.

Alt und neu dürfen nicht beide recht haben. Ist ein Muster gewählt, ersetzt es auf den umgezogenen Routen das vorherige, statt sich daneben anzusammeln. Eine Codebasis, die dauerhaft zwei Konventionen trägt, ist genau der Zustand, den die Migration beenden sollte.

Verifikation pro Route, nicht pro Release. Jede umgezogene Route wird auf Rendering-Modus, Bundle-Größe und Verhalten geprüft, bevor die nächste beginnt.

Wann ein Audit der bessere erste Schritt ist

Wenn Sie einen Verdacht haben statt einer Entscheidung - die Anwendung fühlt sich langsam an, oder fragil, oder teuer zu ändern, und niemand kann genau sagen warum -, beantwortet ein Audit das in zwei Wochen und sagt Ihnen, ob eine Migration überhaupt die richtige Antwort ist. Manchmal ist sie es nicht: der Router ist in Ordnung und das Problem ist eine Rendering-Entscheidung auf vier Routen, was ein sehr viel kleineres Stück Arbeit ist.

Wie es geschnitten ist

Das erste Ergebnis ist eine Karte und keine Migration: welche Routen es gibt, wovon jede abhängt und welche niemand mehr erklären kann.

Daraus entsteht ein phasenweiser Leistungsumfang mit einer Routenzahl und einem Preis je Phase. Der Vertrag bezieht sich auf diese Liste, die Diskussion darüber, was im Umfang liegt, findet also statt, solange sie noch billig ist. Sie können nach jeder Phase aufhören und behalten eine lauffähige Anwendung, und genau diese Eigenschaft macht das Ganze überlebbar.

Dann die Phasen, Route für Route, wobei beide Router laufen, bis die letzte umgezogen ist.

Was Sie erhalten

Die Anwendung auf dem App Router, Route für Route migriert, jede Phase als eigener Pull Request gegen eine vorab vereinbarte Routenliste. Nichts zieht in einer einzigen Änderung um, die zu groß zum Reviewen ist.

Sie bekommen außerdem die Karte, die am Anfang entsteht: welche Routen es gibt, wovon jede abhängt und welche niemand erklären konnte. Dieses Dokument überlebt die Migration und ist meist das Erste, was eine neue Entwicklerin in die Hand bekommt.