Was macht next-cache-components-optimizer?
Zwei Schleifen, gemeinsame Hebel und Primitive, unterschiedliche Diagnosen:
- Page-Render-Schleife (ppr-loop.md) — das statische Gerüst einer einzelnen Seite vergrößern. Bewertet Suspense-Fallback-Bereiche bei einem reinen Gerüst-Rendering.
- Nav-Schleife (instant-nav-loop.md) — wenn der Benutzer von A nach B navigiert, sofort das statische Layout von B anzeigen (Chrome, Struktur, inhaltsförmige Fallbacks), anstatt die UI von A so lange zu halten, bis die Daten von B aufgelöst sind. Erfasst die ausgesetzten Grenzen von B nach dem
pushstate, klassifiziert sie nachsuspended_by[].nameund entfernt SSR-only-Client-Hooks.
Wähle eine aus und führe sie vollständig aus.
Voraussetzungen
next-dev-loopmuss für diese Sitzung gestartet sein — es öffnet den headed Browser, stellt dieagent-browserCLI bereit und verbindet den dev MCP-Server, dermcp get_logsbereitstellt.cacheComponents: trueinnext.config.ts. Andernfalls ablehnen.
Vorbereitung (gemeinsam)
- Bestätige
cacheComponents: true. - Der Benutzer muss sich bereits auf der Seite befinden, die jede Schleife benötigt, im headed Browser (von
next-dev-loop) — eingeloggt, mit eingerichtetem Zustand. Dieser Skill kann keine Authentifizierung, SSO oder MFA durchführen; er nimmt die manuelle Einrichtung als Ausgangspunkt. (Jede Unterschleife gibt an, welche Seite sie erwartet.) agent-browser get url, um die aktuelle Route zu verankern.
Jede Schleife setzt das Instant-Cookie nach Bedarf (siehe gemeinsamen Abschnitt instant cookie unten).
Instant-Cookie (gemeinsam)
Beide Schleifen verwenden das next-instant-navigation-testing-Cookie, um die dynamischen Datenschreiboperationen des Frameworks einzufrieren. Nach dem Setzen ist der sichtbare Inhalt auf der Seite das statische Gerüst plus Suspense-Fallbacks — das erfassen wir, um die Optimierung zu bewerten.
Setze es mit einem ausstehenden Lock-Tupel [0, "<eindeutige-id>"]. Die ID ist ein beliebiger eindeutiger String; die Konvention ist ein p-präfixierter zufälliger Stempel, damit parallele Scopes nicht kollidieren:
agent-browser cookies set next-instant-navigation-testing '[0,"p<zufall>"]' \
--url <origin>
Die Vorbereitung jeder Schleife gibt an, wann sie im Ablauf gesetzt werden soll. Lösche es am Ende (siehe teardown unten).
Entscheide, welche Schleife
- Page-Render, wenn die Beschwerde über die anfängliche Ladezeit einer Route geht. Lese ppr-loop.md.
- Nav, wenn es um die Navigation zwischen zwei Routen geht. Lese instant-nav-loop.md.
Unklar → nachfragen.
Gemeinsame Refactoring-Hebel
- Push down — I/O in ein Suspense-umwickeltes Kind extrahieren, sodass das Elternteil statisch bleibt und statische Geschwister in das statische Gerüst aufsteigen.
- Rekursiv, nicht blind umwickeln. Wenn eine Suspense-Grenze bereits eine Komponente umschließt, die sowohl statischen Inhalt als auch die I/O enthält, lies hinein, extrahiere das I/O-abhängige JSX in ein neues Blatt und hebe die statischen Geschwister nach oben.
- Cache —
'use cache'+cacheLife(<profil>). Frage den Benutzer immer nach der Frische; ordne einem Preset zu (seconds/minutes/hours/days/weeks/max/default).
Push-down und Cache kombinieren sich: Push-down hebt statische Struktur an, Cache eliminiert die verbleibende Datenlücke.
Vorschlag via Plan-Modus (gemeinsam)
Jedes Refactoring durchläuft vor der Anwendung den Plan-Modus. Betrachte dies als Signal: Die Anwendungsarbeit ist nicht triviale, vorlagenbasierte Bearbeitung, sondern anspruchsvolle agentische Entwicklung. Dieser Skill liefert das Framework — welchen Hebel man ansetzt, welchen Kandidaten man repariert, was die erwartete sichtbare Änderung ist — aber die eigentliche Arbeit (welche Datei bearbeitet wird, wie die I/O sauber extrahiert wird, wo die neue Suspense-Grenze platziert wird, welches cacheLife-Profil der Benutzer gefragt wird) ist eine Ermessensentscheidung, die du durchdenken musst. Der Plan-Modus erzwingt einen kohärenten Vorschlag, bevor Code berührt wird, und gibt dem Benutzer die Möglichkeit, bei jeder dieser Entscheidungen umzuleiten.
Kein-Gerüst-Ausstieg (gemeinsam)
Die Hebel setzen voraus, dass ein Gerüst existiert, das vergrößert oder gecacht werden kann. Wenn die Route vollständig blockiert ist — HTTP 500 mit blocking-route oder NEXT_STATIC_GEN_BAILOUT in mcp get_logs, oder null Suspense-Grenzen auf einer sichtbar gerenderten Seite — gibt es kein Gerüst. Zeige den strukturellen Blocker an und halte an; der Benutzer muss den problematischen dynamischen Zugriff in <Suspense> einwickeln, bevor eine der Schleifen helfen kann.
Überprüfung erfordert eine sichtbare Änderung (gemeinsam)
Jede Schleife erfasst einen Basis-Screenshot des Gerüsts vor der Anwendung einer Änderung und dann einen erneuten Screenshot danach. Gib beide Pfade in der endgültigen Zusammenfassung an, damit der Benutzer sehen kann, was sich geändert hat. Die beiden Aufnahmen müssen sich sichtbar unterscheiden — Fallback-Bereich verkleinert, Inhalt zur statischen Oberfläche befördert, Ziel-Fallback verschwunden oder inhaltsförmig. Identisch aussehende Aufnahmen bedeuten, dass das Refactoring nicht durchgeführt wurde; rückgängig machen. „Es kompiliert sauber“ ist nicht das Kriterium.
Blende die Dev-Overlay vor jedem Screenshot aus. Das Next.js-Dev-Overlay (<nextjs-portal> im Dokument-Root) rendert Instant-Navigation-Anleitungen, Build-Fehler und andere Entwicklungs-Chrome, die den Vorher/Nachher-Vergleich verunreinigen. Blende es aus, mache den Screenshot, stelle es wieder her:
agent-browser eval "document.querySelector('nextjs-portal').style.display='none'"
agent-browser screenshot <pfad>
agent-browser eval "document.querySelector('nextjs-portal').style.display=''"
Anti-Patterns (gemeinsam)
Ersetze keine granularen Suspense-Grenzen durch ein Lade-Skelett auf oberster Ebene. Eine loading.tsx für das gesamte Segment oder eine <Suspense fallback={<Skeleton />}> auf Root-Ebene (oder schlimmer noch, fallback={null}, das die UI leer lässt), macht die Optimierung dieses Skills zunichte — die darin besteht, echte statische Chrome oberhalb jeder granularen Grenze zu extrahieren und inhaltsförmige Fallbacks pro Bereich zu verwenden. Ein grober „Seite lädt“-Platzhalter umgeht die gesamte Arbeit.
Fallstricke (gemeinsam)
- Dev prefetcht nicht so wie die Produktion, und Routen kompilieren beim ersten Aufruf — daher aktualisiert sich das DOM nach einer Navigation oder einem Neuladen merklich länger als das endgültige Produktionserlebnis. Warte geduldig, bis das DOM stabil ist, bevor du den React-Baum erfasst oder einen Screenshot machst — z. B.
document.documentElement.innerHTML.lengthabfragen, bis es bei zwei aufeinanderfolgenden Lesevorgängen unverändert bleibt. Eine feste kurze Verzögerung riskiert, mitten im Rendering zu messen. - Versuche nicht, Nav-Prefetch durch Überprüfung des dev-Netzwerkverkehrs zu verifizieren — dev sendet überhaupt keine Prefetch-Anfragen, daher sehen der Netzwerk-Tab, manuelle
router.prefetch()-Aufrufe und<Link prefetch={true}>alle kaputt aus, unabhängig davon, ob dein Code korrekt ist. Das Cookie-gesperrte SPA-Nav-Rezept in instant-nav-loop.md unterverifyist bereits das kanonische Rezept dafür — es simuliert, was die Produktion in das prefetched RSC vorrendern würde, ohne dass Prefetch tatsächlich ausgelöst werden muss. Verwende es; erfinde keine Netzwerk-Tab-Alternative. - Die Diagnose-Pipeline kann instabil sein — das Timing der DevTools-Anbindung, DOM-Settling-Races und Dev-Kompilierungseffekte können jeweils inkonsistente Aufnahmen von einem Durchlauf zum nächsten erzeugen. Wenn ein Ergebnis seltsam erscheint (ein Kandidat erscheint, den du nicht erwartest, oder einer, den du erwartest, erscheint nicht), wiederhole die Diagnose 2–3 Mal und vergleiche kreuzweise; Grenzen, die konsistent erscheinen, sind echt, einmalige Vorkommnisse sind Rauschen.
Referenz (gemeinsame Primitive)
agent-browser react suspense add --only-dynamic, um auf serverseitig tatsächlich
--json ausgesetzte Grenzen zu filtern. Jeder Eintrag hat
jsx_source + suspended_by[] mit rohen Blockernamen
(usePathname, cookies, fetch, cache, ...); nach
Namen für die jeweiligen Schleifenregeln klassifizieren
POST /__nextjs_original-stack-frames body { frames: StackFrame[],
isServer, isEdgeServer,
isAppDirectory }; gibt ein
Ergebnis pro Frame mit
datei:zeile:spalte zurück
mcp get_logs dev MCP-Tool von next-dev-loop;
zeigt blocking-route /
NEXT_STATIC_GEN_BAILOUT 500er an
cacheLife('<profil>') default | seconds | minutes
| hours | days | weeks | max
Schleifenspezifische Primitive in instant-nav-loop.md.
Aufräumen (gemeinsam)
Lösche das Cookie mit Namen — überschreibe mit einem abgelaufenen Stempel:
agent-browser cookies set next-instant-navigation-testing x \
--url <origin> --expires 1
Niemals agent-browser cookies clear (ohne Argumente) — löscht die Authentifizierung.
Geschwister von next-dev-loop — zuerst dieses starten.