next-upgrade

Überblick über den next-upgrade Skill

Was next-upgrade macht

Der next-upgrade Skill hilft einem Agenten dabei, ein reales Next.js-Projekt mit den offiziellen Migrationsleitfäden und Codemods auf eine neuere Major-Version zu aktualisieren, statt aus dem Gedächtnis zu raten. Die Aufgabe ist klar praxisorientiert: die aktuelle next-Version in deiner App erkennen, den sichersten Upgrade-Pfad bestimmen, zuerst die passenden Codemods ausführen, dann Abhängigkeiten aktualisieren und anschließend Breaking Changes prüfen, die noch manuelle Anpassungen erfordern.

Für wen sich dieser next-upgrade Skill eignet

Dieser Skill ist ideal für Entwickler, die eine bestehende Next.js-Codebasis pflegen und ein Upgrade mit einem AI-Assistenten planen oder umsetzen wollen, ohne von den offiziellen Vorgaben abzuweichen. Besonders nützlich ist er, wenn:

• dein Projekt mehr als eine Major-Version zurückliegt
• du einen repo-bewussten Upgrade-Plan statt einer generischen Checkliste willst
• du Hilfe bei versionsspezifischen Codemods und der Abstimmung von Abhängigkeiten brauchst
• du Unterstützung direkt in einem Code-Editing-Workflow möchtest, nicht nur eine Browser-Zusammenfassung

Der eigentliche Job-to-be-done

Die meisten Nutzer brauchen nicht einfach nur „Informationen zu Next.js-Upgrades“. Sie müssen von einer aktuell funktionierenden App auf eine neuere Next.js-Version kommen, ohne Routing, React-Kompatibilität, Build-Ausgaben oder Runtime-APIs zu beschädigen. Genau auf diesen Entscheidungs- und Umsetzungsweg ist der next-upgrade Skill ausgerichtet.

Was next-upgrade von einem normalen Prompt unterscheidet

Ein einfacher Prompt liefert oft nur allgemeine Upgrade-Hinweise. next-upgrade ist enger gefasst und dadurch nützlicher, weil er strukturiert ist rund um:

• das zuerst erfolgende Lesen deiner package.json
• das Prüfen der offiziellen Next.js-Upgrade-Guides für die Zielversion
• das schrittweise Vorgehen bei Sprüngen über Major-Versionen
• die Priorisierung offizieller Codemods vor manuellen Änderungen
• das korrekte gemeinsame Upgrade von next, react und react-dom

Was er dir nicht abnimmt

Der Skill ersetzt keine Validierung. Er kann Codeänderungen und Dependency-Updates anleiten, aber du musst deine App, Tests, Linting und Build-Checks weiterhin selbst ausführen. Außerdem ist er kein Ersatz für frameworkspezifisches Wissen in stark angepassten Setups wie Monorepos, ungewöhnlichen Bundler-Integrationen oder tiefgreifend gepatchtem Server-/Runtime-Verhalten.

So verwendest du den next-upgrade Skill

Installationskontext für next-upgrade

Installiere den Skill in deiner AI-Coding-Umgebung, damit er direkt im Repository aufgerufen werden kann, das du aktualisieren willst. Ein typisches Installationsmuster ist:

npx skills add https://github.com/vercel-labs/next-skills --skill next-upgrade

Wenn deine Umgebung GitHub-Skills aus vercel-labs/next-skills bereits bereitstellt, musst du möglicherweise nur noch next-upgrade direkt aufrufen.

So rufst du next-upgrade in der Praxis auf

Im Repository ist ein Argument-Hinweis [target-version] hinterlegt. Am saubersten ist es daher, die gewünschte Version direkt anzugeben, zum Beispiel:

• Use next-upgrade for Next.js 16
• Run next-upgrade targeting v15
• Apply the next-upgrade skill to move this app from 13 to 15 incrementally

Wenn du die Zielversion noch nicht kennst, lass dir zuerst einen Plan geben:

• Use next-upgrade to inspect this repo and recommend the safest target version

Welche Eingaben der Skill braucht

next-upgrade funktioniert am besten, wenn der Agent Folgendes prüfen kann:

• package.json
• ein Lockfile wie package-lock.json, pnpm-lock.yaml oder yarn.lock
• die Workspace-Konfiguration, falls die App in einem Monorepo liegt
• die Verzeichnisstruktur der App, insbesondere ob du app/ oder pages/ nutzt
• CI- oder Build-Kommandos, mit denen das Upgrade verifiziert wird

Die minimal sinnvollen Eingaben sind:

• aktuelle Next.js-Version
• verwendeter Paketmanager
• gewünschte Zielversion
• ob du nur Planung oder echte Code-Änderungen willst

Wie du aus einem groben Ziel einen starken next-upgrade Prompt machst

Schwacher Prompt:

• Upgrade my app

Besserer Prompt:

• Use next-upgrade to inspect package.json, determine the current Next.js version, upgrade this project to Next.js 15 using official migration guides, run the relevant @next/codemod transforms first, then update next/react/react-dom together and summarize any manual follow-up changes.

Bester Prompt für ein nicht triviales Repo:

• Use next-upgrade for Code Editing on this monorepo app in apps/web. Read apps/web/package.json, identify the current next/react versions, plan the required incremental major upgrades to reach Next.js 16, apply official codemods where relevant, update dependencies with pnpm-compatible commands, and leave a checklist of manual verification steps for build, routing, and runtime APIs.

Diese zusätzliche Präzision verbessert die Ergebnisse deutlich, weil der Skill selbst knapp gehalten ist; dein Prompt liefert Repo-Grenzen, Paketmanager und Ausführungsumfang.

Empfohlener Workflow vor Änderungen

Ein verlässlicher next-upgrade usage-Ablauf sieht so aus:

1. package.json und aktuelle Dependency-Versionen prüfen
2. Zielversion festlegen
3. den offiziellen Next.js-Upgrade-Guide für jeden beteiligten Major-Schritt abrufen
4. Codemods vor manueller Nacharbeit ausführen
5. next, react und react-dom aktualisieren
6. Lint, Typecheck, Tests und Production Build ausführen
7. verbleibende Breaking Changes beheben, die im Guide oder durch Runtime-Fehler sichtbar werden

Wenn du mehrere Versionen zurückliegst, springe nicht blind auf die Zielversion. Bitte den Agenten, 13 -> 14 -> 15 -> 16 als getrennte Upgrade-Schritte zu behandeln.

Repository-Datei, die du zuerst lesen solltest

Starte mit skills/next-upgrade/SKILL.md im Upstream-Repository:

• https://github.com/vercel-labs/next-skills/tree/main/skills/next-upgrade

Der Skill ist kurz, daher gibt es nicht viele unterstützende Dateien zur Prüfung. Der eigentliche Wert steckt im in SKILL.md kodierten Workflow: Version erkennen, offizielle Doku abrufen, schrittweise upgraden, zuerst Codemods ausführen, dann Abhängigkeiten aktualisieren.

Offizielle Dokumentation, von der dieser Skill abhängt

Der Skill verweist ausdrücklich auf die offiziellen Next.js-Upgrade-Ressourcen, darunter:

• Codemods: https://nextjs.org/docs/app/guides/upgrading/codemods
• Versionsleitfäden wie:
  • https://nextjs.org/docs/app/guides/upgrading/version-16
  • https://nextjs.org/docs/app/guides/upgrading/version-15
  • https://nextjs.org/docs/app/guides/upgrading/version-14

Das ist für die Einführung wichtig: next-upgrade ist nur so gut wie die Bereitschaft des Agenten, diese Leitfäden tatsächlich abzurufen und ihnen zu folgen, statt sich auf veraltetes Framework-Wissen zu verlassen.

Beim next-upgrade Guide kommen Codemods zuerst, nicht zuletzt

Eine der stärksten Eigenschaften des next-upgrade guide ist die Reihenfolge. Er weist den Agenten an, offizielle Codemods früh auszuführen:
npx @next/codemod@latest <transform> <path>

Zu den im Skill genannten Beispielen gehören:

• next-async-request-api
• next-request-geo-ip
• next-dynamic-access-named-export

Diese Reihenfolge ist wichtig, weil Codemods wiederkehrende Breaking Changes oft schneller und sicherer abdecken als manuelle Änderungen nach einem Dependency-Bump.

Welche Dependency-Updates du explizit anfordern solltest

Wenn du next-upgrade nutzt, bitte den Agenten ausdrücklich darum, Peer Dependencies gemeinsam zu aktualisieren. Der Skill stellt dieses Muster bewusst in den Mittelpunkt:
npm install next@latest react@latest react-dom@latest

Auch wenn du pnpm oder yarn verwendest, bleibt der Kern derselbe: Behandle next, react und react-dom als abgestimmtes Set, sofern der offizielle Guide nichts anderes vorgibt.

next-upgrade für Code Editing

Für Code Editing ist next-upgrade am nützlichsten, wenn der Agent Dateien sowohl prüfen als auch ändern darf, statt nur einen Plan zu liefern. Gute Aufgaben sind:

• Dependency-Bereiche in package.json aktualisieren
• Codemod-Kommandos anwenden
• APIs anpassen, die von Breaking Changes betroffen sind
• Inline-Kommentare oder eine Migrationszusammenfassung zur manuellen Prüfung hinterlassen

Weniger nützlich ist der Skill, wenn deine Umgebung weder auf Repository-Dateien noch auf externe Doku zugreifen kann, denn sein Vorteil entsteht gerade aus Repo-Inspektion plus Abruf der offiziellen Guides.

Praktische Grenzen und Trade-offs

Nutze next-upgrade, wenn du einen disziplinierten Pfad willst, rechne aber mit einigen Grenzen:

• nicht jede Versionsnuance ist lokal hinterlegt; der Skill setzt auf den Live-Abruf der Guides
• am stärksten ist er bei Standard-Next.js-Apps, nicht bei stark angepasster Infrastruktur
• projektspezifische Testautomatisierung bringt er nicht eingebaut mit
• bei Monorepos, Sub-Apps oder package.json-Dateien außerhalb des Roots braucht er oft zusätzliche Hinweise im Prompt

Kurz gesagt: Der Skill reduziert Rätselraten, aber dein Prompt muss den Scope trotzdem klar setzen.

FAQ zum next-upgrade Skill

Ist next-upgrade besser als ein generischer Upgrade-Prompt?

In der Regel ja, wenn du einen wiederholbaren Upgrade-Prozess willst. Ein generischer Prompt kann plausibel klingende, aber veraltete Ratschläge liefern. next-upgrade ist an offizielle Migrationsleitfäden, Codemods und die Versionserkennung aus deinen Projektdateien gekoppelt.

Ist der next-upgrade Skill anfängerfreundlich?

Ja, mit einer Einschränkung: Einsteiger sollten ihn zunächst im Planungsmodus verwenden. Bitte um:

• Erkennung der aktuellen Version
• Empfehlung für die Zielversion
• auszuführende Codemods
• voraussichtlich nötige manuelle Änderungen
• eine Verifizierungs-Checkliste

So lässt sich die Ausgabe leichter prüfen, bevor du echte Änderungen zulässt.

Muss ich die Zielversion vorher kennen?

Nein. Du kannst next-upgrade bitten, das Repo zu prüfen und die sicherste Zielversion zu empfehlen. Wenn du aber bereits weißt, dass du aus Plattform- oder Dependency-Gründen auf eine bestimmte Version musst, führt die direkte Vorgabe zu einem klareren Plan.

Wann sollte ich next-upgrade nicht verwenden?

Lass next-upgrade aus, wenn:

• du eine neue App erstellst statt eine bestehende zu aktualisieren
• dein Problem nichts mit einer Versionsmigration zu tun hat
• dein Stack von Custom-Internals abhängt, die in der offiziellen Doku nicht abgedeckt sind
• du nur ein einzelnes Kommando brauchst und den exakten Versionspfad bereits kennst

Kann next-upgrade Sprünge über mehrere Versionen hinweg handhaben?

Ja, aber nur schrittweise. Der Skill bevorzugt ausdrücklich stufenweise Major-Upgrades statt eines einzigen blinden Sprungs. Wenn deine App weit zurückliegt, fordere einen gestaffelten Plan mit Checkpoints nach jeder Major-Version an.

Funktioniert er nur für app-router-Projekte?

Nein, aber die offiziellen Guides, die er abruft, betonen unter Umständen neuere Next.js-Muster. Wenn deine Codebasis noch ältere Konventionen nutzt, bitte den Agenten vor Änderungen darum, klar zu unterscheiden, welche Teile des Guides auf dein Repo zutreffen und welche nicht.

So verbesserst du den next-upgrade Skill

Gib next-upgrade klarere Repo-Grenzen

Der schnellste Weg zu besseren Ergebnissen ist, dem Agenten genau zu sagen, wo die Next.js-App liegt. In einem Monorepo solltest du angeben:

• App-Pfad wie apps/web
• Paketmanager
• Workspace-Tool
• ob Änderungen ausschließlich innerhalb dieser App bleiben sollen

Ohne diese Angaben prüft der Skill möglicherweise die falsche package.json oder schlägt Kommandos auf der falschen Ebene vor.

Bitte um eine Ausgabe in zwei Phasen

Ein starkes Muster ist:

1. nur planen
2. Änderungen ausführen

Beispiel:

• Use next-upgrade to first produce an upgrade plan with required codemods and risks. After I approve it, apply the changes.

Das reduziert versehentlich zu breite Änderungen und macht den Skill in produktiven Codebasen vertrauenswürdiger.

Gib stärkere Verifizierungskriterien vor

Bitte nicht nur um „Upgrade successfully“. Fordere den Agenten auf, mit konkreten Kommandos zu prüfen, etwa:

• install
• lint
• typecheck
• unit tests
• production build

Das verbessert die next-upgrade usage, weil der Agent dann auf ein tatsächlich lauffähiges Repo hinarbeiten kann, nicht nur auf aktualisierte Dependency-Zeilen.

Benenne die Ausfall- und Fehlermodi, die dir wichtig sind

Wenn dir das Vermeiden bestimmter Regressionen besonders wichtig ist, sag das ausdrücklich. Zum Beispiel:

• Prioritize route behavior and middleware compatibility
• Watch for request API changes introduced in newer Next.js versions
• Do not migrate unrelated code while applying next-upgrade

Solche Vorgaben führen zu besseren Änderungen als ein pauschales „make it work“.

Bitte um die Begründung der Codemod-Auswahl

Ein nützlicher Verbesserungs-Prompt ist:

• List which @next/codemod transforms apply to this repo and why before running them

So kannst du prüfen, ob der Agent die Transforms wirklich an vorhandene Code-Muster anpasst, statt Codemods wahllos auszuführen.

Häufige Fehlermuster bei next-upgrade

Typische Muster bei schwachen Ergebnissen sind:

• Dependencies aktualisieren, ohne zuerst die aktuelle Version zu prüfen
• Zwischenversionen bei Major-Upgrades überspringen
• manuell editieren, bevor die Codemods geprüft wurden
• die Abstimmung von react und react-dom ignorieren
• in einem Monorepo annehmen, dass die Root-package.json automatisch das App-Paket ist

Wenn du so etwas siehst, stoppe und verlange einen versionsweisen Plan.

Wie du nach der ersten Ausgabe sinnvoll iterierst

Nach dem ersten Durchlauf solltest du eine präzisere zweite Runde anfordern, die sich auf das konzentriert, was fehlgeschlagen ist:

• Re-run next-upgrade analysis based on these build errors
• Compare the remaining errors against the official v15 guide
• Propose the smallest manual edits still needed after codemods

Das ist besser, als komplett von vorn zu beginnen, weil der Skill auf Migrationsschritte ausgelegt ist und nicht auf perfekte One-shot-Ausgaben.

Bestes Prompt-Muster für hochwertigere next-upgrade Ergebnisse

Eine kompakte Vorlage mit viel Signal:

Use next-upgrade on <path>. Detect the current Next.js version from package.json, determine the correct incremental upgrade path to <target-version>, fetch the official migration guides for each step, identify and run the applicable @next/codemod transforms first, then update next/react/react-dom together. After edits, summarize breaking changes addressed, remaining manual follow-ups, and the exact verification commands I should run.

Dieser Prompt gibt dem next-upgrade skill genug Struktur, um deutlich bessere Ergebnisse zu liefern als eine generische Code-Editing-Anfrage.