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. Rufetools/listfü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 einmalagent-browser skills get corefü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/mcpplus der proaktive Kompilierungscheck viaget_compilation_issues. agent-browser>= 0.31.1 – React-Introspection, worktree-scopedsession id, idempotentes--restoreund 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.
- Upgrade Next.js:
pnpm next upgrade(odernpx next upgrade). Docs: https://nextjs.org/docs/app/getting-started/upgrading (Version-16-Guide: https://nextjs.org/docs/app/guides/upgrading/version-16) - Installiere oder upgrade
agent-browser:npm i -g agent-browser@latest. Wenn die CLI nicht imPATHist, installiere sie vor dem Fortfahren – der Preflight erwartet, sie direkt aufrufen zu können.
preflight
Einmal pro Sitzung bestätigen, dass beide Ansichten live sind.
-
Öffne
agent-browsermit 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 jedenagent-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 worktreeverhindert Kollisionen zwischen parallelen Worktrees und kopierten Checkouts. Bloßes--restoreverwendet 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 beiopen; 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 closespeichert den Cookie-Status, sodass das nächsteopenihn wiederherstellt. -
Prüfe
/_next/mcp(tools/list) – bestätige, dass es erreichbar ist undget_compilation_issuesauflistet:- Nicht erreichbar → entweder läuft
next devnicht, oder Next.js ist unter 16.3. Überprüfepackage.json, um dies zu klären, und lehne dann ab. get_compilation_issuesnicht in der Liste → Next.js unter 16.3. Lehne ab und sage dem Benutzer, er solle upgraden.
- Nicht erreichbar → entweder läuft
-
get_compilation_issuesdient gleichzeitig als Turbopack-Prüfung. Eine Fehlerantwort von"Turbopack project is not available..."bedeutet, der Benutzer verwendet webpack. Lehne ab – Turbopack ist erforderlich. -
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-browsersteuert die Seite; behaupte, was der Benutzer tatsächlich sieht. - React-Level-Verhalten –
agent-browsermit 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 sowohlAGENT_BROWSER_SESSION="$SESSION"als auchAGENT_BROWSER_RESTORE="$SESSION"am Anfang jeder Shell, in der du agent-browser ausführst. Wenn du sie nicht exportierst, übergib--session "$SESSION" --restorebei jedem Befehl. - Wenn die beiden Ansichten nicht übereinstimmen, vermute zuerst einen Tooling-Fehler. Wenn
agent-browsersagt, eine Route sei kaputt, aber/_next/mcpund 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. Vermeidewait --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:blankoder ein "no browser session"-Fehler – direkt nachopenoder nach einem Klick (auch wennopendie 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" --restoreund mache einen neuen Snapshot; wenn immer noch leer, führeagent-browser --session "$SESSION" --restore closeaus und dann erneutopen. Falle nicht aufcurlzurü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 derdata:-Zeile mitsed -n 's/^data: //p'(ein einfachessed 's/^data: //'lässt dieevent:-Zeile übrig und das Parsen schlägt fehl).- Nicht-Port-3000-Dev-Server: Lies das
next dev-Banner; setzeNEXT_MCP_URL=http://localhost:<port>/_next/mcp. get_errorsundget_page_metadatabenö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.