Communitygithub.com

next-dev-loop

Überprüft das Laufzeitverhalten von Next.js nach Code-Änderungen. Stellt sicher, dass Änderungen tatsächlich in der laufenden App funktionieren – nicht nur, dass sie kompilieren oder typgeprüft sind. Kombiniert /_next/mcp (Next.js Sicht) mit agent-browser (Browser-Sicht). Erfordert einen laufenden next dev.

Was ist next-dev-loop?

Diese Fähigkeit (Skill) definiert einen geschlossenen Entwicklungs-Workflow für Next.js mit Turbopack. Nach jeder Code-Änderung wird automatisch überprüft, ob die App nicht nur kompiliert, sondern auch zur Laufzeit korrekt funktioniert. Dazu werden zwei unabhängige, aber sich ergänzende Perspektiven genutzt: Der /_next/mcp-Endpunkt von Next.js selbst (kennt Framework-Interna wie Routen, RSC, Server Actions) und der agent-browser, der einen echten Chrome-Browser steuert und DOM, Konsole, Netzwerk und React-Komponenten inspizieren kann. Der Skill durchläuft einen definierten Preflight (Sicherstellung der Versionen und beider Live-Ansichten), dann eine Schleife aus vorheriger Analyse und nachträglicher Verifikation, die vier Fehlermodi prüft: Kompilierung, Laufzeitfehler, korrektes Verhalten (DOM-Assertionen) und React-spezifische Aspekte (Render-Zyklen, Suspense). Der Skill ist für die Verwendung mit Claude Code, Cursor und anderen KI-Agenten konzipiert, die Next.js-Apps bearbeiten und sicherstellen müssen, dass Änderungen die App nicht beschädigen.

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

In Ihrer bevorzugten KI fragen

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

Dokumentation

Was macht next-dev-loop?

Der Edit/Verify-Rhythmus während next dev – mache eine Änderung, dann bestätige, dass sie tatsächlich zur Laufzeit funktioniert, nicht nur, dass die Typen oder der Build zufrieden sind.

Du überprüfst über zwei Ansichten derselben laufenden App:

  • /_next/mcp – ein HTTP-Endpunkt, den Next.js über sich selbst bereitstellt. Kennt frameworkspezifische Dinge: Routen, Segmente, RSC, Server Actions, Server-Logs und Fehler, wie Next.js sie sieht. Rufe tools/list für die aktuelle Oberfläche auf.
  • agent-browser – eine CLI, die einen echten Chrome steuert. Kennt framework-agnostische Browser-Dinge: DOM, Konsole, Netzwerk, React Fiber, Vitals. Führe vor der Verwendung einmal agent-browser skills get core für die versionsangepasste Bedienungsanleitung aus – rate keine Unterbefehle aus dem Gedächtnis.

Die beiden Ansichten prüfen sich gegenseitig.

erfordert

  • Next.js 16.3+ mit Turbopack – /_next/mcp plus der proaktive Kompilierungscheck via get_compilation_issues.
  • agent-browser >= 0.31.1 – React-Introspection, worktree-scoped session id, idempotentes --restore und Launch-Flag-Abstimmung.

Dies sind harte Untergrenzen, keine weichen Präferenzen. Wenn etwas fehlt, sage dem Benutzer, wie er upgraden soll, und stoppe. Falle nicht zurück auf das Durchsuchen des Quellcodes oder auf eine schwächere Prüfung – dieser Skill setzt voraus, dass beide Ansichten live sind und die oben genannten Versionen erfüllen.

preflight

Einmal pro Sitzung bestätigen, dass beide Ansichten live sind.

  1. Öffne agent-browser mit der Ziel-URL und stelle den gespeicherten Login-Status wieder her, wenn vorhanden. Leite zuerst eine stabile Session-ID für dieses Checkout ab und verwende sie für jeden agent-browser-Befehl:

    SESSION="$(agent-browser session id --scope worktree --prefix next-dev-loop)"
    export AGENT_BROWSER_SESSION="$SESSION"
    export AGENT_BROWSER_RESTORE="$SESSION"
    

    Öffne dann die Ziel-URL:

    agent-browser --session "$SESSION" --restore --headed --enable react-devtools open <url>
    

    --scope worktree verhindert Kollisionen zwischen parallelen Worktrees und kopierten Checkouts. Bloßes --restore verwendet die Session-ID als Persistenzschlüssel, lädt gespeicherte Cookies/localStorage vor der Navigation, wenn vorhanden, und speichert den Status beim Schließen automatisch. Übergib immer die gewünschten Launch-Flags bei open; agent-browser wird seinen bereichsbezogenen Hintergrundstatus je nach Bedarf wiederverwenden, neu starten oder neustarten.

    Der Browser gehört dem Benutzer. Wenn der Status nicht wiederhergestellt wurde (erster Start, abgelaufene Sitzung) und die Seite geschützt ist, führt der Benutzer den Login durch – pausiere, bis er bestätigt. Nach dem Login fahre mit derselben Sitzung und demselben Wiederherstellungskontext fort; agent-browser close speichert den Cookie-Status, sodass das nächste open ihn wiederherstellt.

  2. Prüfe /_next/mcp (tools/list) – bestätige, dass es erreichbar ist und get_compilation_issues auflistet:

    • Nicht erreichbar → entweder läuft next dev nicht, oder Next.js ist unter 16.3. Überprüfe package.json, um dies zu klären, und lehne dann ab.
    • get_compilation_issues nicht in der Liste → Next.js unter 16.3. Lehne ab und sage dem Benutzer, er solle upgraden.
  3. get_compilation_issues dient gleichzeitig als Turbopack-Prüfung. Eine Fehlerantwort von "Turbopack project is not available..." bedeutet, der Benutzer verwendet webpack. Lehne ab – Turbopack ist erforderlich.

  4. get_routes → deine Routenkarte für den Rest der Sitzung.

loop

vor dem Edit – den Umfang eingrenzen

Frage die laufende App, nicht die Codebasis. /_next/mcp weiß, welche Dateien die aktuelle Route gerendert haben; verwende diese als deinen Suchbereich. Laufzeitintrospection bleibt günstig, während die Codebasis wächst; agentisches Suchen nicht.

nach dem Edit – überprüfen

Vier Fehlermodi. Überprüfe jeden:

  • Kompiliert – get_compilation_issues.
  • Läuft ohne Fehler – /_next/mcp (Server- und hochgereichte Browser-Fehler tauchen beide hier auf).
  • Verhält sich wie beabsichtigt – agent-browser steuert die Seite; behaupte, was der Benutzer tatsächlich sieht.
  • React-Level-Verhalten – agent-browser mit aktivierten react-devtools gibt den Komponentenbaum, Props, State und Render-Zählungen preis. Verankere Framework-Level-Prüfungen hier (zusätzliche Renderings, Server/Client-Grenzverschiebungen, Suspense-Fallbacks) – DOM-Assertionen allein übersehen sie.

Wähle das spezifische Tool aus tools/list oder dem agent-browser-Handbuch und nicht aus dem Gedächtnis.

gotchas

  • Jeder agent-browser-Befehl muss deine Session und deinen Restore-Key kennen, sonst könnte er einen leeren Standardbrowser verwenden oder das Speichern des Login-Status fehlschlagen. Am einfachsten: Exportiere sowohl AGENT_BROWSER_SESSION="$SESSION" als auch AGENT_BROWSER_RESTORE="$SESSION" am Anfang jeder Shell, in der du agent-browser ausführst. Wenn du sie nicht exportierst, übergib --session "$SESSION" --restore bei jedem Befehl.
  • Wenn die beiden Ansichten nicht übereinstimmen, vermute zuerst einen Tooling-Fehler. Wenn agent-browser sagt, eine Route sei kaputt, aber /_next/mcp und der Server sagen, sie sei sauber gerendert, ist eine veraltete oder falsch geleitete Browser-Sitzung die wahrscheinlichere Ursache als ein echter Bug – gleiche die Ansichten ab, bevor du die App debuggen.
  • Bestätigen eines Klicks oder einer Navigation: Die Seite beruhigt sich etwas später, also warte mit wait --load networkidle (kein Pfad, den man falsch machen kann), dann snapshot/read, um die Seite zu bestätigen. Vermeide wait --url, es sei denn, du übergibst den exakten href des Links – ein geratener oder Platzhalter-Pfad stimmt nicht mit der echten URL überein und timeoutet nach 25s.
  • Ein leerer Read, leerer Snapshot, about:blank oder ein "no browser session"-Fehler – direkt nach open oder nach einem Klick (auch wenn open die Seite gemeldet hat) – bedeutet, dass der Browser die Seite verwirft (eine veraltete Sitzung), keine kaputte Route. Öffne deine Sitzung an der URL erneut mit --session "$SESSION" --restore und mache einen neuen Snapshot; wenn immer noch leer, führe agent-browser --session "$SESSION" --restore close aus und dann erneut open. Falle nicht auf curl zurück; es umgeht den Browser, den du testest.
  • React-Introspection-Ausgabe ist nach einer Navigation veraltet. Führe erneut aus.
  • /_next/mcp-Antworten sind SSE – lies das JSON von der data:-Zeile mit sed -n 's/^data: //p' (ein einfaches sed 's/^data: //' lässt die event:-Zeile übrig und das Parsen schlägt fehl).
  • Nicht-Port-3000-Dev-Server: Lies das next dev-Banner; setze NEXT_MCP_URL=http://localhost:<port>/_next/mcp.
  • get_errors und get_page_metadata benötigen mindestens eine Navigation, um sich zu füllen.

referenz

Alle unten stehenden Tools sind vorhanden, sobald der Preflight bestanden ist. Wenn tools/list fehlt eines davon, hätte der Preflight ablehnen sollen – überprüfe erneut.

# /_next/mcp                 notizen
get_project_metadata         projectPath, devServerUrl, bundler
get_routes                   fs-scan; keine Browser-Sitzung nötig
get_errors                   runtime + build; benötigt eine Browser-Sitzung;
                             beinhaltet vom Dev-Server abgefangene Browser-Fehler
get_page_metadata            segment-trie + routerType; benötigt eine Browser-
                             Sitzung; verwende als Entdeckungs-Abkürzung für
                             welche Dateien eine Route antreiben
get_logs                     gibt logFilePath zurück
get_server_action_by_id      gehashte ID → datei + funktionsname
get_compilation_issues       nur Turbopack; Fehler bei webpack
                             ("Turbopack project is not available")

teardown

Schließe die Sitzung mit demselben Sitzungs- und Wiederherstellungskontext: agent-browser --session "$SESSION" --restore close. close speichert die Cookies und den Storage dieser Sitzung, sodass das nächste open mit --restore den Benutzer eingeloggt hält. Lasse next dev für die nächste Schleife laufen.


next-dev-loop-<topic>-Geschwister (z. B. next-dev-loop-rsc, next-dev-loop-debug) gehen davon aus, dass dieser Preflight bereits ausgeführt wurde; sie setzen an der Schleife ein.

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

Optimize a Next.js app that has `cacheComponents: true` — either the static shell on first paint, or the in-app navigation between routes. Picks the matching diagnostic loop and runs it.

Verwandte Skills