Communitygithub.com

next-cache-components-adoption

Aktiviere Cache Components in einer Next.js-App und behebe die dadurch auftretenden blockierenden Routen.

Was ist next-cache-components-adoption?

Diese Skill-Anleitung beschreibt den schrittweisen Prozess zur Aktivierung von Cache Components in einer Next.js-App (ab Version 16.3) und zur Behebung der dabei auftretenden Build-Fehler. Cache Components erfordern, dass jede Route vorgerendert werden kann. Routen, die zur Laufzeit auf Anfragedaten zugreifen (z.B. `cookies()`, `params`) oder synchrone I/O-Operationen verwenden (z.B. `new Date()`, `crypto.randomUUID()`), blockieren den Build und müssen angepasst werden. Die Skill bietet zwei Strategien: **Inkrementell** (zuerst eine Codemod ausführen, um alle Routen von der Validierung auszunehmen, dann Route für Route adoptieren) oder **Direkt** (direkt die blockierenden Fehler beheben). Sie verweist auf die offiziellen Next.js-Dokumente und die `next-dev-loop` Skill für die Überprüfung im Browser. Das Ziel ist ein erfolgreicher Build, bei dem Entwickler die Kontrolle darüber behalten, welche Routen dynamisch bleiben (`export const instant = false`) und welche durch `"use cache"` oder `<Suspense>` optimiert werden.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/0n6k4v-Coder/skills/tree/HEAD/next.js/next-cache-components-adoption

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht next-cache-components-adoption?

Aktiviere Cache Components in einer App und führe sie zu einem erfolgreichen Build. Diese Skill sequenziert die Arbeit; Fehlerbehebungen für einzelne Fehler befinden sich in den Dev-Overlay-Reparaturkarten und in der Build-Terminal-Ausgabe. Der Leitfaden zur Migration zu Cache Components ist die kanonische Referenz für die Konzepte und API-spezifischen Rezepte, die diese Skill anwendet – konsultiere ihn immer, wenn die Skill-Schritte ein Muster erwähnen ("use cache", cacheLife, <Suspense>-Platzierung usw.) und du die vollständige Erklärung wünschst.

Voraussetzungen

  • App Router-Projekt. Cache Components ist eine Funktion des App Routers; cacheComponents: true hat keine Wirkung auf pages/-Routen. Wenn das Projekt einen pages/- oder src/pages/-Baum, aber keinen app/- oder src/app/-Baum hat, stoppe und informiere den Benutzer – die Migration von Pages zu App ist ein eigenes Projekt und nicht Teil dieser Skill. Eine Hybrid-App (sowohl pages/ als auch app/) ist in Ordnung: Das Flag betrifft die app/-Routen; pages/-Routen sind nicht betroffen und benötigen keine Ausnahmen.

  • Next.js 16.3 oder neuer. Diese Version enthält die Bestandteile, auf die sich diese Skill stützt: top-level cacheComponents, export const instant, die Dev-Overlay-Validierungswarnungen für die sofortige Navigation und die Codemod cache-components-instant-false. Wenn next --version eine Version unter 16.3 anzeigt, aktualisiere zuerst:

    • npx @next/codemod@latest upgrade latest um die versionsspezifischen Codemods anzuwenden.
    • Lese den entsprechenden Versions-Upgrade-Leitfaden (z.B. Version 16) für das, was die Codemod nicht abdeckt.
  • Keine inkompatiblen Konfigurationsschlüssel. cacheComponents: true führt bei Dateien, die noch dynamic, revalidate oder fetchCache exportieren, zu Fehlern. Übersetze, lösche nicht. Jeder Export kodiert ein Verhalten, das die Route beibehalten muss; migriere jeden einzelnen über die schlüsselspezifischen Abschnitte des Migrationsleitfadens in sein Cache Components-Äquivalent. Wenn ein Wert noch nicht sauber übersetzt werden kann, hinterlasse einen // TODO: Cache Components adoption — restore revalidate = 3600-Kommentar, damit die Schleife ihn aufgreift. Die Codemod cache-components-instant-false berührt diese nicht.

  • experimental.dynamicIO ist fatal. Es wurde in das top-level cacheComponents umbenannt, und der alte Schlüssel bricht den Build jetzt ab – entferne ihn (oder ersetze ihn durch cacheComponents: true) zuerst. experimental.useCache wird noch als veraltetes Alias akzeptiert; es ist redundant, sobald cacheComponents: true gesetzt ist, also entferne es zur Klarheit.

Hinweise

  • Keine funktionierende Basislinie vor dem Flag. Wenn die App bereits "use cache" verwendet, schlägt der Build vor dem Setzen des Flags mit dem Fehler please enable the feature flag cacheComponents fehl. Das Setzen des Flags ist das Erste, was du tust (inkrementell vor der Codemod, direkt vor der Fehlerbehebung) – nicht etwas, das du nach einem erfolgreichen Build tust. Vermerke dies in deiner Zusammenfassung zu Beginn, damit es nicht wie eine Regression aussieht.

  • Offline-Dokumentation. Offline-Kopien der Leitfaden-Links befinden sich unter node_modules/next/dist/docs/, wobei die Verzeichnisstruktur für die Sortierung nummeriert ist (z.B. node_modules/next/dist/docs/01-app/02-guides/migrating-to-cache-components.md). Der letzte Dateiname entspricht dem Slug. Wenn du das nummerierte Präfix nicht vorhersagen kannst, löst find node_modules/next/dist/docs -name '<slug>.md' es auf. Die /docs/messages/* Fehlerseiten sind nicht gebündelt. Wenn die Offline-Dokumentation vollständig fehlt, führe npx @next/codemod@latest agents-md aus, um einen versionsgemäßen Index in AGENTS.md / CLAUDE.md zu schreiben.

Die Struktur der Arbeit

Es gibt eine Schleife: Durchlaufe den Routenbaum von oben nach unten, eine Funktion nach der anderen, und adoptiere jede Route mit next dev + einem Browser. Der Build ist eine abschließende Überprüfung für jede Funktion, nicht die Arbeitsumgebung.

Die Wahl in Schritt 1 ist, ob zuerst die Validierungsfehler unterdrückt oder sie sofort behoben werden. In beiden Fällen ist die Schleife dieselbe:

  • Mit einem ruhigen Vorschritt (Inkrementell). Führe die Codemod aus, um jede Seite und jedes Layout von der Validierung auszunehmen. Sobald du auch das behoben hast, was die Codemod nicht kann (synchrone I/O-Aufrufe, übrig gebliebene revalidate/dynamic/fetchCache-Exporte), ist der Build erfolgreich; du lieferst dies als eigenen PR aus und beginnst dann die Schleife – entferne nach und nach eine Ausnahme und adoptiere diese Route. Zerlegt die Arbeit in kleine, überprüfbare PRs.
  • Ohne (Direkt). Aktiviere cacheComponents und beginne die Schleife mit dem, was der Build zuerst meldet. Gleiche Schleife, aber jede Korrektur befindet sich auf einem Branch, bis die Adoption abgeschlossen ist.

In beiden Fällen ist das Erfolgskriterium pro Route dasselbe: Die Dev-Schleife meldet keine Fehler UND next build ist erfolgreich. Frage den Benutzer nach jeder Funktion. Erwarte, die meiste Zeit in der Schleife zu verbringen, nicht im Vorschritt.

Hintergrund

cacheComponents: true erfordert, dass jede Route vorgerendert werden kann. Eine Route, die Anfragedaten außerhalb von <Suspense> liest, ist "blockierend" und führt zu einem Build-Fehler. export const instant = false markiert eine Route als blockierungsfähig, was sie sowohl in der Entwicklung als auch im Build freigibt; bei einem Layout deckt es den gesamten darunter liegenden Teilbaum ab. Lesevorgänge, die in eine "use cache"-Funktion eingebettet sind, gelten als Cache-Grenzen, nicht als blockierende Lesevorgänge.

Drei Klassen von Blockierern treten in dieser Reihenfolge auf:

  1. Anfragezeit-Lesevorgänge (cookies(), headers(), await params, await searchParams). Alle vier blockieren, wenn sie am Anfang einer Seite oder eines Layouts abgewartet werden. params und searchParams werden oft übersehen, weil sie nicht als "Anfragedaten" wie Cookies und Header kategorisiert werden. Die Lösung besteht darin, den Lesevorgang in ein <Suspense>-gewickeltes Kind zu verschieben – und bei params/searchParams das Promise an das Kind weiterzugeben und es dort abzuwarten; warte nicht am Seitenanfang.
  2. Synchrone I/O zur Modul-/Renderzeit (new Date(), Date.now(), Math.random(), crypto.randomUUID()). Diese führen selbst mit instant = false zu Build-Fehlern – die Ausnahme unterdrückt sie nicht. Wenn sie sich in einem gemeinsamen Layout befinden, blockieren sie jede Route darunter. Die Codemod kann sie nicht beheben; du musst jede einzelne übersetzen (mit "use cache" zwischenspeichern, wenn sie stabil ist, oder in await connection() + <Suspense> einwickeln, wenn sie pro Anfrage erfolgt), bevor der Build erfolgreich sein kann. Durchsuche das gesamte Repository vor der Ausführung nach diesen Aufrufen.
  3. "use cache"-Dateien, die Anfragedaten lesen. Eine Datei mit einer top-level "use cache"-Direktive kann kein instant exportieren; die Kombination führt zum Fehler Only async functions are allowed to be exported in a "use cache" file. und bedeutet, dass die Direktive für diese Route falsch war. Entferne sie vor der Ausführung der Codemod.

Arbeitsumgebungen

Auffinden blockierender Routen

Bevorzuge next dev gegenüber next build während der Arbeit.

  • next dev – die Arbeitsumgebung. Besuche eine Route; ihre Blockierungsfehler erscheinen im Dev-Overlay mit vollständigen Stack-Traces und Reparaturkarten, die auf die dokumentationsspezifischen Fehlerseiten verlinken. Arbeite eine Route nach der anderen – Fehler sammeln sich nicht an einer Stelle. Die Route selbst gibt dennoch HTTP 200 zurück, lies also das Overlay (oder .next-dev.log), nicht die Statuscodes. Ein leeres Overlay ist eine Hälfte des "Route sauber"-Zustands – die andere Hälfte ist die Browser-Überprüfung (siehe Schritt 2) und ein erfolgreicher Build für diese Route.
  • next build – nur zur Erkennung. Der Build ist die autoritative Überprüfung für next dev, nicht sein Ersatz. Verwende ihn als letzte Hürde für jede Funktion in der Schleife (ein erfolgreicher Build ist Teil des Erfolgskriteriums pro Route) und als abschließende Überprüfung für die gesamte App. Im inkrementellen Modus bestätigt der Build auch den Vorschritt (Codemod hat jede Route ausgenommen, kein gemeinsames Layout hat noch einen synchrone I/O-Blockierer), bevor du diesen PR auslieferst. Greife nicht während der Arbeit an einer Route zum Build, anstatt die Dev-Schleife zu verwenden – ein sauberer Kompilierungsfehler sagt dir nicht, was in der statischen Shell gelandet ist und was gestreamt wurde. Standardmäßig stoppt der Build bei der ersten blockierenden Route, daher ist er auch schlecht für die Einschätzung des Arbeitsumfangs. Zwei Flags helfen bei der Iteration: --debug-build-paths baut nur die von dir benannten Routen (kommagetrennte Glob-Muster von Dateipfaden relativ zum Projektstamm, z.B. --debug-build-paths="app/admin/**/page.tsx" – keine URL-Pfade; --debug-build-paths="app/(marketing)/about/page.tsx" – nicht /about; --debug-build-paths="app/admin" trifft nichts und baut stillschweigend null Routen), und --debug-prerender deaktiviert den vorzeitigen Abbruch, sodass der Build über den ersten Vorab-Rendering-Fehler hinaus fortfährt, jede blockierende Route meldet und einen detaillierteren Stack-Trace ausgibt, der die Ursprungsdatei und -zeile nennt.

Jeder Blockierungsfehler hat eine Dokumentationsseite – öffne sie. Sowohl das Dev-Overlay als auch das Build-Terminal geben einen https://nextjs.org/docs/messages/<slug>-Link mit jedem Fehler aus. Diese Seite ist das kanonische Rezept für die Behebung; die Inline-Nachricht ist eine Zusammenfassung. Rufe den Link für jeden unterschiedlichen Fehler ab, den du siehst, selbst wenn du denkst, das Muster zu kennen – die Rezepte entwickeln sich weiter, und derselbe Fehlertyp kann je nach dem, was die Route liest, unterschiedliche korrekte Korrekturen erfordern. Improvisiere nicht basierend auf der Inline-Nachricht allein. (/docs/messages/*-Seiten sind nicht offline gebündelt; wenn du kein Netzwerk hast, greife auf die API-spezifischen Leitfäden unter node_modules/next/dist/docs/ zurück und vermerke die Einschränkung, wenn du berichtest.)

Überprüfung jeder Korrektur zur Laufzeit

Ein erfolgreicher Build oder ein leeres Overlay ist kein Beweis dafür, dass sich die Route tatsächlich korrekt verhält – Cache Components ist ein Laufzeitthema (eine statische Shell mit gestreamten Daten). Überprüfe nach jeder Korrektur, nicht erst am Ende.

In bevorzugter Reihenfolge:

  1. next-dev-loop – stark bevorzugt. Kreuzt /_next/mcp mit dem Live-Browser via agent-browser ab und deckt sowohl Kompilierungs- als auch Laufzeitprobleme in einem Durchgang auf. Die Diagnostik (React-Baum, Suspense-Grenzen, Console + Netzwerk) ist umfangreicher als das händische Herumprobieren mit next dev.

    Installiere es vor Beginn der Schleife. Warte nicht, bis du auf etwas stößt, das next dev allein nicht erklären kann. Führe aus:

    npx skills add https://github.com/vercel/next.js/tree/canary/skills/next-dev-loop
    

    Die Skill erfordert agent-browser >= 0.27.0 und führt dich durch.

    Erfordert Turbopack. Wenn das dev-Skript in package.json --webpack übergibt, weise den Benutzer darauf hin und frage, ob es einen Grund gibt, bei webpack zu bleiben. Wenn nicht, wechsle zu Turbopack (Standard ab Next.js 16.3+). Wenn sie webpack behalten möchten, überspringe diese Installation und verwende stattdessen die Nur-Build-Schleife.

    Du benötigst keine Erlaubnis, next-dev-loop selbst zu installieren. Es ist ein Werkzeug, wie die Installation einer Dev-Abhängigkeit. Wenn ein Benutzer in der Leitung ist, informiere ihn kurz, dass du es zur Überprüfung installierst. In einem nicht-interaktiven Durchlauf (CI, Dashboard, Sandbox) installiere es ohne Nachfrage – "Ich kann den Benutzer nicht fragen" ist kein Grund, es zu überspringen. Die einzigen legitimen Überspringungen sind echte technische Hürden: kein Netzwerk, kein npm, read-only Dateisystem, eine erklärte "Keine neuen Abhängigkeiten"-Richtlinie oder ein reines webpack-Dev-Skript. Wenn du überspringst, nenne die spezifische Hürde in deinem Abschlussbericht.

  2. Ein Browser, den du selbst steuern kannst. Playwright, agent-browser direkt, jedes Browser-Automatisierungswerkzeug. Verwende nur, wenn next-dev-loop wirklich blockiert ist. Dir entgehen die Framework-seitigen Prüfungen (/_next/mcp), daher erkennen DOM-Assertionen allein nicht jede Regression – sei vorsichtiger bei dem, was du als "verifiziert" bezeichnest.

  3. Nur Build. Wenn du überhaupt keinen Dev-Server ausführen kannst, ist der Build dein einziges Signal. ○ (Static)-Routen ohne <Suspense> sind durch den Build vollständig verifiziert (nichts zu testendes Gestreamtes). ◐ (Partial Prerender)-Routen sind nur in der Shell verifiziert – markiere sie, wenn du Bericht erstattest.

  4. Überhaupt keine Werkzeuge. Bitte den Benutzer, den Dev-Server (oder Build) auszuführen und zu berichten, was er sieht, oder committe den erreichten Meilenstein und gib ab.

Schritt 1: Wähle eine Strategie

Frage den Benutzer. Formuliere es als Frage zur PR-Struktur, nicht als Frage zum Umfang. Verwende niemals die internen Bezeichnungen (Inkrementell, Direkt, Meilenstein A), wenn du mit dem Benutzer sprichst – das sind deine eigenen Konzepte. Frage in Bezug auf PRs und Funktionen, z.B.: "Möchtest du, dass ich zuerst einen PR öffne, der Cache Components aktiviert und jede Route von der Validierung ausnimmt, und dann die eigentlichen Route-Adoptionen funktionsweise in Folge-PRs behandle? Oder alles auf einem Branch erledigen?" Selbst bei einer winzigen App hat der inkrementelle Pfad noch Wert (überprüfbarer PR, rückgängig zu machen, die // TODO: Cache Components adoption-Marker dienen gleichzeitig als deine Aufgabenliste für die nächste Sitzung). Entscheide nicht in ihrem Namen.

Wenn es keinen Benutzer zu fragen gibt, standardmäßig Inkrementell und dokumentiere die Wahl.

  • Inkrementell – ruhiger Vorschritt + die Schleife. Führe die Codemod aus, um jede Seite und jedes Layout von der Validierung auszunehmen, bringe den Build zum Laufen, stoppe und stimme dich mit dem Benutzer ab (siehe Ende des Vorschritts: Prüfung), dann betrete Schritt 2s Schleife und liefere jede Funktion als Folge-PR aus.
  • Direkt – überspringe den Vorschritt. Aktiviere cacheComponents und gehe direkt zu Schritt 2s Schleife; die blockierenden Routen des Builds sind die Aufgabenliste.

Inkrementell

Behebe vor der Ausführung der Codemod die beiden Blockierer-Klassen, die sie nicht beheben kann.

  1. Synchrone I/O zur Modul-/Renderzeit. Durchsuche das gesamte Repository nach new Date(), Date.now(), Math.random() und crypto.randomUUID() (nicht nur app/**/layout.{js,jsx,ts,tsx} – der Lesevorgang könnte in jeder Komponente leben, die von einem Layout importiert wird). Übersetze jede Fundstelle mit dem Rezept aus ihrer blocking-prerender-* Fehlerkarte.

  2. Inkompatible Segment-Konfigurationen. Suche nach ^export const (revalidate|dynamic|fetchCache) im gesamten app/-Verzeichnis und übersetze gemäß dem Hinweis im Abschnitt "Voraussetzungen". Die Codemod berührt sie nicht; wenn sie an Ort und Stelle bleiben, führt der Build nach der Codemod fehl.

Die Codemod weigert sich, auf einem dreckigen Arbeitsbaum ausgeführt zu werden. Committe oder stash zuerst unabhängige Arbeiten, oder übergib --force, damit ihre Bearbeitungen neben deinen laufenden Änderungen landen können. Häufige Fehlannahme: Wenn du kürzlich Next.js aktualisiert hast, sind package.json und die Lockdatei bereits dreckig – committe diese zuerst.

Verwende den @canary

…

[gekürzt für die Übersetzung]

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

Verwandte Skills