Next.js 15 auf 16 upgraden: Codemods, Breaking Changes und ein sicherer Ablauf

Ein Next.js-Projekt läuft zuverlässig – und dann kommt die Frage: Wann ist der richtige Zeitpunkt für das Major-Upgrade? Seit dem 21. Oktober 2025 ist Next.js 16 die aktive Version. Die Maintenance-Phase von Next.js 15 endet nach der Support-Policy zwei Jahre nach dem Release, also am 21. Oktober 2026; danach sind laut Policy keine Sicherheitsupdates mehr zugesagt.

Wer heute auf Next.js 15.x läuft, ist technisch nicht sofort in Gefahr – die letzte 15.x-Version (15.5.28, veröffentlicht am 14. Oktober 2026) schließt alle bis zu diesem Zeitpunkt bekannten Lücken. Aber gegen künftig entdeckte Schwachstellen gibt es nach dem Policy-Ende keine zugesagte Backport-Versorgung mehr. Das ist kein theoretisches Risiko: Allein zwischen Mai und Oktober 2026 gab es Security-Releases in jedem Monat – darunter zwei kritische RCE-Lücken in der Image Optimization API.

Das eigentliche Problem beim Upgrade ist selten die Motivation. Es ist der Umfang. Turbopack als neuer Standard-Build-Prozess, die vollständige Entfernung synchroner Request-APIs, middleware → proxy, die Streichung von next lint – das alles summiert sich zu einem Aufwand, den viele Teams unterschätzen. Dieser Leitfaden zeigt, was konkret zu tun ist, in welcher Reihenfolge, und wo manuelle Eingriffe unvermeidlich sind.

Voraussetzungen prüfen, bevor der erste Befehl läuft

Bevor Codemods oder Paketaktualisierungen stattfinden, müssen drei Mindestversionen sichergestellt sein. Next.js 16 unterstützt Node.js 18 nicht mehr. Die Mindestanforderung laut offiziellem Upgrade-Guide ist Node.js 20.9.0 – das ist auch in den engines-Feldern von next@16.4.2 auf npm hinterlegt.

Für TypeScript gilt eine Mindestversion von 5.1.0. Browser-seitig werden Chrome 111+, Edge 111+, Firefox 111+ und Safari 16.4+ vorausgesetzt. Wer noch auf älteren Browsern rendern muss, sollte das vor dem Upgrade klären – die Minima sind im Framework hart kodiert.

Zu React: Der offizielle Upgrade-Guide nennt React 19.2 und empfiehlt, die jeweils neuesten Versionen von Next.js und React zu installieren. Die peerDependencies von next@16.4.2 erlauben formal react ^18.2.0 || ^19.0.0. Ob der App Router mit React 18 vollständig unterstützt wird, ist nicht abschließend dokumentiert – die Empfehlung des Guides lautet eindeutig: React auf die aktuelle Version bringen.

Wer in einer Managed-Hosting-Umgebung oder einem CI-System unterwegs ist, sollte die Node.js-Version dort zuerst anheben – ein Build gegen Node.js 18 schlägt ab Next.js 16 bereits beim Starten fehl.

Was Next.js 16 gegenüber 15 grundlegend verändert

Die Breaking Changes dieses Majors lassen sich grob in vier Kategorien einteilen: Build-Infrastruktur, Request-APIs, Linting und kleinere Verhaltensänderungen in Image, Routing und Caching.

Turbopack ist jetzt Standard – auch für next build

In Next.js 15 war Webpack der Standard-Bundler; Turbopack war opt-in für next dev. Ab Version 16 ist Turbopack der Standard für next dev und next build. Das ist die gravierendste operative Änderung, weil sie bestehende Webpack-Konfigurationen sofort bricht.

Konkret: Wer in next.config.js oder next.config.ts eigene Webpack-Plugins, Loader oder Konfigurationsblöcke definiert hat, wird nach dem Upgrade keinen erfolgreichen Build mehr erhalten. Der Ausweg ist entweder die Migration auf die Turbopack-API oder das temporäre Flag --webpack bzw. --turbopack, das explizit zwischen den Bundlern wählen lässt:

# Turbopack explizit (Standard):
next build --turbopack

# Webpack als Fallback (temporär, bis Migration vollständig):
next build --webpack

Der Codemod aktualisiert next.config automatisch, um Turbopack zu konfigurieren – aber eigene Webpack-Blöcke muss man manuell portieren. Bis das vollständig abgeschlossen ist, ist --webpack ein sinnvoller Übergangsmechanismus.

Synchroner Zugriff auf Request-APIs vollständig entfernt

In Next.js 15 wurde der synchrone Zugriff auf cookies(), headers(), draftMode(), params und searchParams als deprecated markiert. In Next.js 16 ist dieser Zugriff vollständig entfernt. Wer cookies().get('session') schreibt, erhält keinen Compile-Error, aber die Funktion verhält sich nicht mehr wie erwartet – oder der Build schlägt fehl.

Das gilt auch für die Props von opengraph-image, twitter-image, icon, apple-icon sowie das id-Feld in sitemap. Alle diese müssen auf async/await umgestellt werden.

Hypothetisches Beispiel: Eine Route Handler-Funktion, die bisher synchron auf cookies() zugriff, sieht nach der Migration so aus:

// Vorher (Next.js 15, noch erlaubt):
export function GET() {
  const cookieStore = cookies();
  const session = cookieStore.get('session');
  // ...
}

// Nachher (Next.js 16, Pflicht):
export async function GET() {
  const cookieStore = await cookies();
  const session = cookieStore.get('session');
  // ...
}

Der Codemod next-async-request-api übernimmt den Großteil dieser Umstellung automatisch. In komplexen Fällen – zum Beispiel wenn params innerhalb von Middleware-ähnlichen Hilfsfunktionen verwendet wird – ist manuelle Nacharbeit nötig.

middleware → proxy: Datei und Runtime ändern sich

Die bisherige middleware.ts ist in Next.js 16 deprecated. Der neue Mechanismus heißt proxy – sowohl die Datei als auch der Export werden umbenannt. Der wesentliche Unterschied: proxy läuft nur auf Node.js, nicht auf der Edge Runtime. Wer Middleware bisher gezielt auf Edge deployt hat (z. B. auf Vercel's Edge Network für minimale Latenz), muss diesen Aspekt explizit prüfen und die Deployment-Strategie anpassen.

Der Codemod erledigt die Umbenennung; die Runtime-Implikationen sind manuell zu bewerten.

next lint entfernt – Linting muss separat laufen

Ab Next.js 16 gibt es den Befehl next lint nicht mehr. Der next build-Prozess führt kein Linting mehr durch. Die Option eslint in next.config ist ebenfalls entfernt. ESLint Flat Config ist jetzt Standard.

Das ist eine stille Änderung, die CI-Pipelines brechen kann, wenn dort next lint als Qualitätsgate läuft. Der Codemod next-lint-to-eslint-cli migriert die Konfiguration auf die direkte ESLint-CLI. In der package.json muss das lint-Skript angepasst werden:

// Vorher:
"lint": "next lint"

// Nachher (nach Codemod-Migration):
"lint": "eslint ."

Wer ESLint bisher über Next.js konfiguriert hat, muss die eslint.config.js (Flat Config) manuell prüfen und ggf. fehlende Regeln ergänzen.

Weitere Breaking Changes im Überblick

revalidateTag braucht jetzt ein zweites Argument: In Next.js 16 erfordert revalidateTag ein cacheLife-Profil als zweites Argument, z. B. revalidateTag('posts', 'max'). Fehlt dieses Argument, verhält sich Caching anders als erwartet.

serverRuntimeConfig und publicRuntimeConfig entfernt: Wer diese Felder in next.config.js nutzt, muss auf Umgebungsvariablen (process.env.*) umsteigen. Das ist kein optionaler Refactor mehr.

AMP-Support vollständig entfernt: AMP-Seiten und die zugehörigen Konfigurationsoptionen existieren in Next.js 16 nicht mehr. Projekte, die noch AMP nutzen, müssen diese Seiten vor dem Upgrade migrieren oder entfernen.

experimental.ppr, experimental.dynamicIO und experimental.useCache entfernt: Der Ersatz ist cacheComponents. Wer diese experimentellen Flags aktiv nutzt, muss die Konfiguration umstellen – der Codemod entfernt unstable_-Präfixe und experimental_ppr automatisch.

next/image mit neuen Defaults: Die Defaults für die Image Optimization haben sich geändert: minimumCacheTTL steigt von 60 Sekunden auf 4 Stunden, qualities ist jetzt nur noch [75], imageSizes enthält nicht mehr den Wert 16, maximumRedirects ist auf 3 begrenzt, und lokale IPs sind standardmäßig blockiert. Query-Strings bei lokalen Bildern erfordern images.localPatterns.search. next/legacy/image und images.domains sind deprecated.

Parallel-Route-Slots brauchen default.js: Wer Parallel Routes nutzt, muss für jeden Slot explizit eine default.js anlegen, sonst schlägt der Build fehl. Das ist eine häufige stille Falle beim Upgrade.

Getrennte Output-Verzeichnisse: next dev und next build nutzen jetzt separate Output-Verzeichnisse (.next/dev) plus ein Lockfile. Deployment-Skripte, die das .next-Verzeichnis direkt referenzieren, müssen ggf. angepasst werden.

Scroll-Verhalten: Das Framework überschreibt scroll-behavior: smooth nicht mehr automatisch. Wer dieses Verhalten beibehalten möchte, muss data-scroll-behavior="smooth" explizit setzen.

size/First Load JS aus next build-Ausgabe entfernt: Wer diese Werte für Performance-Monitoring in CI-Logs auswertet, muss eine alternative Messmethode einrichten.

Der empfohlene Upgrade-Ablauf: Branch für Branch, Schritt für Schritt

Ein Major-Upgrade direkt auf dem Hauptbranch durchzuführen ist unnötig riskant. Der folgende Ablauf hat sich für diese Art von Breaking-Change-Migrations bewährt – nicht als abstraktes Best-Practice-Muster, sondern weil jeder Schritt einen klar abgrenzbaren Zustand erzeugt, den man testen und bei Bedarf zurückrollen kann.

Schritt 1: Eigenen Upgrade-Branch anlegen

git checkout -b upgrade/nextjs-16

Alle folgenden Änderungen laufen auf diesem Branch. Das hält den Produktionsbranch unberührt und ermöglicht einen sauberen Rollback-Punkt.

Schritt 2: Abhängigkeiten aktualisieren

npm install next@latest react@latest react-dom@latest
# oder mit pnpm:
pnpm add next@latest react@latest react-dom@latest

Danach sofort npm ls next ausführen, um sicherzustellen, dass keine doppelte Next.js-Version durch Sub-Dependencies eingeschleppt wird.

Schritt 3: Codemods ausführen

Der primäre Codemod übernimmt den Großteil der automatisierten Migration:

npx @next/codemod@canary upgrade latest
# oder mit pnpm:
pnpm dlx @next/codemod@canary upgrade latest

Dieser Codemod stellt next.config auf Turbopack um, migriert next lint auf die ESLint-CLI, benennt middleware → proxy um, entfernt unstable_-Präfixe und experimental_ppr. Er verändert keine Anwendungslogik und macht keine Annahmen über Deployment-Infrastruktur.

Für die async Request-API-Migration läuft zusätzlich:

npx @next/codemod@canary next-async-request-api .

Und für die ESLint-CLI-Migration separat, falls noch nicht abgedeckt:

npx @next/codemod@canary next-lint-to-eslint-cli .

Für Projekte, die typsichere Props nutzen: Ab Next.js 15.5 gibt es npx next typegen, das PageProps, LayoutProps und RouteContext automatisch generiert. Wer das noch nicht eingerichtet hat, sollte es jetzt nachholen.

Schritt 4: Manuelle Nacharbeit

Nach den Codemods beginnt der entscheidende Teil: manuell prüfen, was nicht automatisch migriert werden kann.

• Webpack-Konfiguration: Jeden Block in next.config prüfen, der webpack oder config.module.rules modifiziert. Prüfen, ob Turbopack-Äquivalente vorhanden sind – oder --webpack-Flag temporär setzen.
• Parallel Routes: Alle @slot-Verzeichnisse durchsuchen und prüfen, ob eine default.js vorhanden ist.
• revalidateTag-Aufrufe: Im gesamten Codebase nach revalidateTag( suchen und jeweils das zweite Argument (cacheLife-Profil) ergänzen.
• next/image-Nutzung: Prüfen, ob images.domains oder next/legacy/image noch im Einsatz sind, und auf remotePatterns bzw. next/image migrieren. Die neuen Defaults bei minimumCacheTTL und qualities können das Bildverhalten im Produktivsystem sichtbar verändern.
• AMP-Seiten: Falls vorhanden, vollständig entfernen oder durch reguläre Next.js-Seiten ersetzen.
• serverRuntimeConfig/publicRuntimeConfig: Alle Vorkommen in next.config und im Code auf process.env.* umstellen.
• CI-Konfiguration: Das lint-Skript und ggf. Build-Befehle in .github/workflows oder vergleichbaren Pipeline-Definitionen anpassen. Sicherstellen, dass Linting explizit als separater Schritt läuft.
• proxy-Runtime: Wenn middleware.ts bisher mit export const config = { runtime: 'edge' } lief, muss die neue proxy-Datei auf Node.js-Kompatibilität geprüft werden.
• Deployment-Skripte: Prüfen, ob .next/dev vs. .next Auswirkungen auf Build-Artefakte und Deploy-Pfade hat.

Schritt 5: Build und Tests

next build

Beim ersten Build-Versuch nach dem Upgrade ist es normal, mehrere Fehler zu sehen. Die Ausgabe ist in der Regel präzise und zeigt, welche Dateien betroffen sind. Jeden Fehler einzeln adressieren, nicht versuchen, alle auf einmal zu „fixen".

Nach einem grünen Build: Unit-Tests, Integration-Tests und – wenn vorhanden – E2E-Tests mit Cypress oder einem vergleichbaren Tool ausführen. Besonderes Augenmerk auf Routen mit Parallel Slots, Middleware-ähnliche Logik und alle Stellen, die cookies(), headers() oder params verwenden.

Schritt 6: Staging-Deployment und manuelle Prüfung

Den Branch auf eine Staging-Umgebung deployen, die der Produktion möglichst nah ist – gleicher Node.js-Version, gleicher Infrastruktur, gleiche Umgebungsvariablen. Dort manuell kritische User Flows durchlaufen: Authentifizierung, Caching-Verhalten, Bilder, alle Routen, die revalidateTag nutzen.

Lighthouse oder Core Web Vitals im Staging messen. Turbopack kann andere Bundle-Größen und Build-Outputs erzeugen als Webpack – das ist kein Bug, aber es sollte dokumentiert sein.

Schritt 7: Merge, Rollout und Monitoring

Erst wenn Staging grün ist, den Branch in den Hauptbranch mergen und in Produktion deployen. Für mindestens 24–48 Stunden nach dem Deployment engeres Monitoring auf Fehlerraten, Build-Logs und Application-Errors einrichten. Sollte ein kritisches Problem auftreten, ist der Rollback auf den letzten Produktionsstand der schnellste Weg – deshalb war der Upgrade-Branch entscheidend.

Ein reales Projekt als Orientierung: Booking-Frontend auf Next.js

Bei der Entwicklung und Betreuung von Next.js-Projekten für Unternehmen – darunter Buchungs-Frontends wie das MobiKart-Kartbahn-System und das HPS Pitbike-Portal – begegnen uns bei Major-Upgrades regelmäßig dieselben Stellen: Webpack-Plugins für SVG-Handling, synchrone Cookie-Zugriffe in Session-Logik und CI-Pipelines, die next lint als Gate nutzen. Keine dieser Stellen ist nach dem Codemod automatisch fertig – sie sind aber vorhersehbar, wenn man den Breaking-Changes-Katalog systematisch abarbeitet.

Als hypothetisches Beispiel: Ein mittelgroßes Buchungsprojekt mit 80 Routen, eigenem Webpack-SVG-Loader, fünf Parallel-Route-Slots und zehn revalidateTag-Aufrufen würde realistisch zwei bis drei Tage für den vollständigen Upgrade-Ablauf benötigen – inklusive Staging-Tests und CI-Anpassung. Projekte ohne Webpack-Customizing und ohne Parallel Routes kommen deutlich schneller durch.

Wann das Upgrade besonders aufwendig wird

Nicht jedes Projekt ist gleich komplex. Folgende Faktoren erhöhen den Aufwand erfahrungsgemäß deutlich:

• Eigene Webpack-Konfiguration (Loader, Plugins, Module-Rules): Turbopack kennt keine direkte Eins-zu-eins-Übersetzung aller Webpack-Plugins – manche müssen durch Alternativen ersetzt werden.
• Viele async-Umstellungen: Bei großen Codebasen mit hunderten von Dateien, die cookies() oder headers() synchron aufrufen, läuft der Codemod zwar durch, aber Edge Cases – z. B. innerhalb von Higher-Order-Functions – müssen manuell geprüft werden.
• Middleware mit Edge-Runtime-Anforderungen: proxy läuft nur auf Node.js. Wer Edge-spezifisches Verhalten (z. B. Geolocation, A/B-Testing auf Vercel Edge) implementiert hatte, braucht eine Alternativlösung.
• AMP-Seiten: Diese müssen vor dem Upgrade vollständig migriert sein. Es gibt keinen Codemod-Pfad für AMP.
• Unvollständige Test-Abdeckung: Wer keine E2E-Tests hat, entdeckt Breaking Changes erst im Staging oder in Produktion.

Wer auf der anderen Seite ein Standard-App-Router-Projekt ohne Webpack-Anpassungen, ohne Parallel Routes und ohne AMP betreibt, kann das Upgrade in vielen Fällen an einem halben Tag durchziehen.

Was nach dem Upgrade anders ist – dauerhaft

Nach einem erfolgreichen Upgrade auf Next.js 16 laufen next dev und next build standardmäßig mit Turbopack. Das verändert Build-Zeiten (in der Regel schneller), Output-Struktur (.next/dev für Development) und die Fehlerausgabe bei Build-Problemen. CI-Metriken, die auf die alte Build-Ausgabe (z. B. First Load JS-Werte) angewiesen sind, müssen neu kalibriert werden.

Linting ist jetzt ein eigenständiger Prozess, den man aktiv in CI einbinden muss. Das ist technisch besser – aber es passiert nicht mehr automatisch. Wer bisher next build als implizites Lint-Gate nutzte, verliert diese Absicherung ohne explizite Anpassung.

revalidateTag mit cacheLife-Profil bedeutet, dass Caching-Strategien expliziter sein müssen. Das ist eine Verbesserung für die Vorhersehbarkeit des Cache-Verhaltens, erfordert aber, dass man sich bewusst für ein Profil entscheidet.

Migration selbst durchführen oder begleiten lassen?

Für erfahrene Next.js-Teams mit gut dokumentierter Konfiguration ist das Upgrade selbst durchführbar – dieser Leitfaden liefert dafür die nötige Grundlage. Der offizielle Upgrade Guide von Vercel deckt alle Breaking Changes vollständig ab und ist die verbindliche Primärquelle.

Sinnvoll ist externe Begleitung, wenn: das Projekt eine komplexe Webpack-Konfiguration hat, die Middleware auf Edge-Runtime angewiesen ist, keine ausreichende Test-Abdeckung vorhanden ist oder das Upgrade unter Zeitdruck in einem laufenden Produktionsprojekt stattfinden muss. In diesen Fällen überwiegt das Risiko eines unvollständigen oder überstürzten Upgrades den Aufwand, es mit einem erfahrenen Partner strukturiert abzuwickeln.

SW Business Solutions führt Next.js-Upgrades mit diesem Ablauf durch: Branch-basiert, mit Codemod-Ausführung, systematischer manueller Nacharbeit, Staging-Tests und dokumentiertem Rollback-Plan. Wer das Upgrade zu Next.js 16 sicher und nachvollziehbar umgesetzt haben möchte, kann direkt ein Erstgespräch vereinbaren.

Wenn Sie sich zunächst einen Überblick über das Support-Ende von Next.js 15 und die strategischen Konsequenzen verschaffen möchten, empfiehlt sich der Begleitartikel Next.js 15 End of Life: Was das Support-Ende für Unternehmen bedeutet.

Für Projekte, die Next.js als Basis für Unternehmensanwendungen einsetzen – von Corporate Websites bis hin zu komplexen SaaS-Anwendungen – ist das Upgrade auf die aktive Major-Version keine optionale Haushaltsaufgabe, sondern Teil einer nachhaltigen Betriebsstrategie.