Communitygithub.com

next-cache-components-optimizer

Optimiert eine Next.js-App mit `cacheComponents: true` — entweder das statische Gerüst beim ersten Rendern oder die Navigation zwischen Routen. Wählt die passende Diagnose-Schleife und führt sie aus.

Was ist next-cache-components-optimizer?

Dieser Skill optimiert eine Next.js-Anwendung, die `cacheComponents: true` in der Konfiguration gesetzt hat. Er bietet zwei spezialisierte Diagnose-Schleifen: die Page-Render-Schleife (`ppr-loop.md`), die das statische Gerüst einer einzelnen Seite vergrößert, und die Nav-Schleife (`instant-nav-loop.md`), die die Navigation zwischen zwei Routen durch sofortiges Anzeigen des statischen Layouts der Zielseite beschleunigt. Der Skill verwendet einen gemeinsamen Satz von Hebeln und Primitiven, darunter die „Instant Cookie“-Technik, um dynamische Daten zu frieren, sowie Refactoring-Ansätze wie „Push down“ (Auslagern von I/O in Suspense-Kinder) und „Cache“ (Nutzung von `'use cache'` + `cacheLife`). Der Skill ist für den Einsatz mit Claude Code, Cursor oder Codex konzipiert und erfordert eine vorherige Initialisierung des `next-dev-loop`-Skills sowie eine manuelle Authentifizierung im Browser. Er betont die Bedeutung einer sichtbaren Verbesserung („visible delta“) vor und nach der Optimierung, die durch Screenshots dokumentiert wird, und warnt vor Anti-Patterns wie dem Ersetzen von granularen Suspense-Grenzen durch ein grobes Lade-Skelett.

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

In Ihrer bevorzugten KI fragen

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

Dokumentation

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 nach suspended_by[].name und entfernt SSR-only-Client-Hooks.

Wähle eine aus und führe sie vollständig aus.

Voraussetzungen

  • next-dev-loop muss für diese Sitzung gestartet sein — es öffnet den headed Browser, stellt die agent-browser CLI bereit und verbindet den dev MCP-Server, der mcp get_logs bereitstellt.
  • cacheComponents: true in next.config.ts. Andernfalls ablehnen.

Vorbereitung (gemeinsam)

  1. Bestätige cacheComponents: true.
  2. 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.)
  3. 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.length abfragen, 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 unter verify ist 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.

Individual skills in this repo

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

0n6k4v-Coder/skills

Translates Figma motion and animations into production-ready application code. Use when implementing animation/motion from a Figma design — user mentions "implement this motion", "add animation from Figma", "animate this component", provides a Figma URL whose node is animated, or when `get_design_context` returns motion data or instructs you to call `get_motion_context`.

0n6k4v-Coder/skills

Motion / animation context for the `use_figma` MCP tool — animating Figma nodes via manual keyframes, animation styles, easing, and timeline duration. Load alongside figma-use whenever a task involves adding, editing, or inspecting animation on a node.

0n6k4v-Coder/skills

Generate motion specification annotations from After Effects timeline data. Use when the user mentions "motion", "motion spec", "animation spec", "timeline", or wants to document a component's animation properties.

0n6k4v-Coder/skills

Turn on Cache Components in a Next.js app and resolve the blocking routes it surfaces. Use when the user wants to enable, adopt, or migrate to Cache Components, flip the `cacheComponents` flag, work through a flood of blocking-prerender / instant validation errors, run the `cache-components-instant-false` codemod, or decide between opting routes out with `export const instant = false` and fixing them in place.

0n6k4v-Coder/skills

Verify Next.js runtime behavior after editing app code. Use this skill to confirm a change actually works in a running app — not just that it compiles or type-checks. Combines /_next/mcp (Next.js's view) with agent-browser (the browser's view). Requires a running `next dev`.

Verwandte Skills