Vor drei Wochen saß ich donnerstagnachmittags im Seahawk-Büro und war ziemlich sicher, dass das Upgrade von Next.js 15 auf 16 auf einer meiner persönlichen Portfolio-Sites maximal vierzig Minuten dauern würde. Es dauerte den Rest des Tages. Und ehrlich gesagt? Das Changelog bereitet dich nicht wirklich auf die Teile vor, die tatsächlich kaputtgehen.
Ich habe bis jetzt über 12.000 Sites gebaut und deployed. Ich sag das nicht, um zu prahlen, ich sag es, weil ich genug von diesen Migrationen gemacht habe, um zu wissen, wann das offizielle Upgrade-Guide etwas beschönigt. Next.js 16 beschönigt einiges. Also hier sind meine echten Notizen, aufgeschrieben so, wie ich mir gewünscht hätte, dass sie mir jemand aufschreibt.
---
Warum ich überhaupt upgradet habe
Turbopack. Das ist die kurze Antwort.
Die längere Antwort ist, dass zwei meiner Sites auf Next.js 14 standen, eine war bereits auf 15, und ich beobachtete die Turbopack-Geschichte seit etwa achtzehn Monaten. Version 16 ist das erste Release, bei dem Turbopack standardmäßig für next dev aktiviert ist. Das ist kein nebensächliches Detail. Bei einem mittelgroßen E-Commerce-Projekt, das ich letztes Jahr für eine Fashion-Kundin gemacht habe, waren die Cold-Start-Zeiten in der Entwicklung brutal, wir sprechen von 12 bis 18 Sekunden beim ersten Load. Falls Turbopack das wirklich reduziert, lohnt sich der Migrationsaufwand.
Spoiler: es reduziert das wirklich. Bei der gleichen Projektklasse sehe ich 3 bis 4 Sekunden kalt. Das ist real.
Aber der Weg dorthin hat einige scharfe Kanten.
---
Der eigentliche Upgrade-Befehl (und was du zuerst ausführen solltest)
Bevor du irgendetwas anfasst, führe ein vollständiges Audit deiner aktuellen Config durch. Ich nutze jetzt regelmäßig npx @next/codemod@latest. Es wird nicht alles erfassen, aber es erfasst die offensichtlichen Umbennennungen und veralteten API-Aufrufe. Führe es aus, committe das Ergebnis, dann erhöhe dein package.json-Version.
Das Upgrade selbst:
- Aktualisiere next,
reactundreact-domzu ihren Zielversionen inpackage.json - Führe
npm installaus (oderpnpm install, falls du vernünftig bist, ich bin seit zwei Jahren bei pnpm) - Führe den Codemod aus:
npx @next/codemod@latest upgrade - Starten
next devund lies jede Warnung, bevor du eine Komponente anfasst - Behebe Config-Probleme, bevor du Komponenten-Probleme behebst, die Reihenfolge zählt hier
Der Codemod-Schritt ist, wo ich gesehen habe, dass Leute scheitern. Sie überspringen ihn, treffen auf drei separate Fehler, und verbringen eine Stunde damit, Dinge zu suchen, die auto-behoben worden wären. Überspring es nicht.
---
next.config.js-Änderungen, die dir weh tun werden
Das war die erste echte Überraschung für mich. Die Konfigurations-API hat sich mehr verschoben, als ich erwartet habe.
Der `experimental`-Block ist jetzt schlanker
Mehrere Flags, die das letzte Jahr oder zwei über im experimentellen Zustand waren, wurden entweder in den stabilen Bereich hochgestuft (und auf die oberste Ebene verschoben) oder ganz entfernt. Die zwei, auf die ich persönlich gestoßen bin:
experimental.appDirist weg. App Router ist jetzt einfach das Standard-Setup. Wenn du das in deiner Config hast, wirft es eine Warnung (und in manchen Setups einen echten Fehler).experimental.serverComponentsExternalPackageswurde aufserverExternalPackagesauf der obersten Ebene deiner Config hochgestuft.
Die zweite hat mich auf einer Website erwischt, die Prisma nutzt. Der Build ist auf dem Server Bundle stillschweigend fehlgeschlagen und ich habe wahrscheinlich vierzig Minuten lang auf die falsche Datei gestarrt, bevor ich es gesehen habe. Überprüf deine next.config.js von oben bis unten, bevor du davon ausgehst, dass eine Component schuld ist.
Turbopack-Config lebt an einem neuen Ort
Wenn du eine Custom-Webpack-Config hattest und du wechselst zu Turbopack (das wirst du, weil es jetzt Standard für dev ist), musst du wissen, dass deine webpack()-Funktion in next.config.js nicht angewendet wird, wenn Turbopack läuft. Es gilt nur während next build, das immer noch Webpack nutzt.
Das ist relevant, wenn du Custom-SVG-Handling hattest (ich nutze SVGR auf den meisten Projekten), Custom-Module-Aliases oder irgendwelche Loader-Konfiguration. Du wirst diese im neuen turbopack-Config-Block replizieren müssen. Die Next.js Turbopack-Dokumentation ist tatsächlich brauchbar zu diesem Punkt, es lohnt sich vorher zu lesen, bevor du davon ausgehst, dass etwas kaputt ist.
---
React 19 Kompatibilität: Die stille Landmine
Next.js 16 kommt mit React 19 als seine Peer Dependency. Wenn du von Next.js 14 hochfährst (15 übersprüngst), machst du zwei React-Majorversionen auf einmal. Da wird es spicy.
Das größte Problem, auf das ich gestoßen bin, war mit älteren Third-Party-Component-Bibliotheken. Ich hatte eine Client-Website mit einer Table-Bibliothek, die intern ReactDOM.render() nutzte. React 19 hat diese API ganz entfernt, sie war seit React 18 veraltet, aber sie funktionierte noch. In 19 wirft sie. Hart.
Das habe ich einen Dienstagmorgen damit verbracht. Die Fehlermeldung deutet dir nicht sofort auf die Bibliothek hin; sie sagt dir nur, dass ReactDOM.render nicht mehr unterstützt wird. Führe npm ls react aus, um zu sehen, welche Packages in deinem Tree widersprüchliche React-Peer-Dependency-Deklarationen haben. Dieser Befehl allein hat mir wahrscheinlich zwei Stunden Rätselraten erspart.
Ein paar Muster, die es wert sind, bei React 19 speziell gewusst zu werden:
forwardRefist nicht mehr erforderlich, um Refs zu übergeben; Refs sind jetzt ein reguläres Prop. Alte Components mitforwardReffunktionieren immer noch, aber du wirst Deprecation-Warnungen sehen.use()ist jetzt stabil und genuinely nützlich für async Daten in Client-Components. Ich habe angefangen, es gegenüberuseEffect+ state für unkomplizierte Fetches zu bevorzugen.- Server Actions haben strengere Type-Anforderungen. Wenn du etwas Lose-Typisiertes in deinen Action-Signaturen hattest, wird TypeScript es jetzt finden.
---
App Router: Was sich beim Caching-Verhalten geändert hat
Das ist subtil und es wird dich in Production erwischen, wenn du nicht aufpasst.
Zurück in Next.js 14 wurde fetch() in Server Components aggressiv standardmäßig gecacht. Du musstest dich mit { cache: 'no-store' } abmelden. In Next.js 15 haben sie das umgekehrt (fetch ist standardmäßig ungecacht), und Next.js 16 setzt diese Richtung fort mit ein paar explizitere Kontrollen.
Wenn du von 14 zu 16 in einem Sprung migriert hast (wie ich es auf einer meiner Websites getan habe), werden deine Seiten, die sich auf das alte Standard-Caching-Verhalten verlassen haben, beginnen, Live-Fetches bei jeder Anfrage zu machen. Für manche Seiten ist das ok. Für andere wird es deine API bombardieren und deine Response-Zeiten in den Keller fahren.
The fix is explicit: use export const revalidate = 3600 (or whatever interval makes sense) at the route segment level, or pass { next: { revalidate: 3600 } } directly in your fetch call. The Next.js caching documentation has a solid breakdown of what caches what and when.
Ich habe jeden Data-Fetching-Route auf der betroffenen Website mit einem schnellen grep nach fetch( überprüft und explizite Caching-Deklarationen hinzugefügt. Dauerte etwa zwei Stunden, aber es war es wert, Response-Zeiten gingen von ~800ms Durchschnitt zurück auf ~120ms nach dem Fix.
---
Turbopack in der Praxis: Das Gute und das Nervige
Lass mich ehrlich mit dir sein: Turbopack ist beeindruckend. Cold-Start-Zeiten sind dramatisch besser. Hot-Module-Replacement fühlt sich bei den meisten Änderungen nahezu instant an. Für die tägliche Entwicklung ist das ein sinnvolles Quality-of-Life-Upgrade.
Aber es gibt raue Kanten.
Was noch nicht funktioniert
Zu der Zeit, als ich diese Migrationen machte, gab es noch eine Handvoll Dinge, die unter Turbopack für dev noch nicht vollständig unterstützt waren:
- Einige Webpack-spezifische Loader haben noch kein Turbopack-Äquivalent. SVGR benötigte eine Konfigurationsänderung (die Turbopack-Regeln-Syntax unterscheidet sich von Webpacks
module.rules). - Custom Babel Transforms. Turbopack verwendet nur SWC. Wenn dein Projekt eine
.babelrcoderbabel.config.jsmit Custom Plugins hat, werden diese nicht ausgeführt. Das ist eine bekannte Limitierung und das Vercel-Team ist transparent darüber in ihrer Turbopack-Dokumentation. - Ein paar PostCSS-Plugin-Kombinationen verhalten sich in der Entwicklung unerwartet. Ich habe das bei Tailwind v4 + Custom-PostCSS-Setup gesehen, die Lösung war, die PostCSS-Plugin-Reihenfolge explizit festzulegen.
Das `--turbopack`-Flag ist jetzt unnötig
Da Turbopack Standard für next dev in Version 16 ist, brauchst du das --turbopack-Flag nicht mehr. Wenn du es in deinen package.json-Scripts vom Experimentieren mit Version 15 noch hast, schadet es nichts, aber es ist redundant. Räum deine Scripts auf.
---
TypeScript- und ESLint-Konfigurationsaktualisierungen
Zwei Verwaltungsaufgaben, die mich verwirrt haben.
Next.js 16 erfordert jetzt TypeScript 5.x. Wenn du noch TypeScript 4.x verwendest (einige ältere Projekte tun das), musst du das separat aktualisieren. Führe npx tsc --version aus, bevor du etwas anderes startest.
Die ESLint-Konfigurationsgeschichte hat sich auch geändert. Next.js 16 wird mit ESLint 9-Unterstützung ausgeliefert, und ESLint 9 verwendet ein Flat-Config-Format (eslint.config.js) statt des alten .eslintrc-Formats. Wenn du noch das alte Format verwendest, fällt Next.js elegant zurück, aber du siehst eine Warnung. Ich habe zwei meiner Projekte ohnehin zur Flat-Config migriert. Es ist ehrlich gesagt sauberer, wenn du die anfängliche Hürde überwunden hast.
---
Meine Migrations-Checkliste (In dieser Reihenfolge)
Das würde ich jedem in meinem Team geben, der dieses Upgrade durchführt:
- Sichere deine aktuellen Konfigurationsdateien und Lockdatei, bevor du etwas anfasst
- Überprüfe deine Node.js-Version, Next.js 16 erfordert Node 18.18 oder später
- Führe
npx @next/codemod@latest upgradein der aktuellen Version aus - Erhöhe next-, react- und react-dom-Versionen in
package.jsonund installiere - Überprüfe
next.config.jsauf hochgestuften oder entferntenexperimental-Flags - Führe
npm ls reactaus, um Konflikte von Drittanbieter-Bibliotheken zu identifizieren - Durchsuche deine Codebasis nach
fetch(und überprüfe Caching-Deklarationen - Überprüfe auf
.babelrcoder Webpack-spezifische Loader, die Turbopack-Äquivalente benötigen - Starte dev, lies alle Warnungen, bevor du Components anfasst
- Führe einen Production-Build lokal aus (
next build), bevor du irgendwo deployst - Deploye in eine Staging-Umgebung und führe einen vollständigen manuellen Smoke-Test durch
Dieser letzte Schritt klingt offensichtlich. Aber ich habe gesehen, wie Leute Staging überspringen und bei „kleinen" Upgrades direkt in Production gehen. Eine Caching-Verhaltensänderung, die deine Homepage bei jedem Request eine Live-API abfragen lässt, ist keine kleine Sache.
---
FAQ
Ist Next.js 16 stabil genug für die Produktion?
Ja, für die meisten Anwendungsfälle. Die Turbopack-for-dev-Änderung ist die größte Verschiebung, und da Production Builds immer noch Webpack nutzen, ist dein tatsächlicher deployed Output weniger betroffen als dein Dev-Experience. Die Caching-Verhaltensänderungen sind die größere Production-Sorge, und diese lassen sich einfach überprüfen, wenn du methodisch vorgehst.
Muss ich React gleichzeitig auf 19 aktualisieren?
Technisch unterstützt Next.js 16 React 18 als Minimum, aber die neuen Features (wie der stabile use()-Hook und die ref-as-prop-Änderung) erfordern React 19. Wenn du an einem Projekt mit vielen Third-Party-Dependencies arbeitest, lohnt es sich, die Kompatibilität zu überprüfen, bevor du dich gleichzeitig auf React 19 festlegst. Der React 19 Upgrade Guide ist lesenswert zusammen mit den Next.js Migration Docs.
Meine benutzerdefinierte Webpack-Config ist unter Turbopack weg. Was mache ich?
Deine Webpack-Config läuft immer noch während next build. Für Dev musst du die relevanten Teile mit dem turbopack-Schlüssel in next.config.js replizieren. Die Syntax ist anders, besonders bei File Transforms und Aliases. Schau dir die offizielle Turbopack Config Reference an und rechne damit, eine bis zwei Stunden daran zu verbringen, wenn deine Webpack-Config komplex ist.
Wie viel schneller ist Turbopack wirklich?
Bei den Projekten, die ich getestet habe: Cold Start fiel von 12–18 Sekunden auf 3–4 Sekunden. HMR bei Component-Änderungen ging von 1–3 Sekunden auf unter 200ms in den meisten Fällen. Das sind ungefähre Zahlen und werden je nach Projektgröße variieren, aber der Unterschied ist spürbar bei allem außer Spielzeugprojekten.
---
Das Upgrade lohnt sich. Turbopack's Dev Speed allein ändert, wie du dich beim Arbeiten in einer großen Next.js-Codebasis fühlst. Geh einfach mit offenen Augen in die Caching-Änderungen und die Third-Party-Library-Kompatibilitätsprüfungen hinein, diese zwei Dinge sind dort, wo die meiste Zeit tatsächlich hingeht.
Nimm dir eine Site nach der anderen vor. Ich habe es gemacht.