Que fait next-dev-loop ?
Le rythme édition/vérification pendant next dev — faites une modification, puis
confirmez qu'elle fonctionne réellement à l'exécution, et pas seulement que les types ou
la compilation sont corrects.
Vous vérifiez à travers deux vues de la même application en cours d'exécution :
/_next/mcp— un point de terminaison HTTP que Next.js expose à propos de lui-même. Connaît des éléments spécifiques au framework : routes, segments, RSC, actions serveur, logs serveur et erreurs telles que Next.js les a vues. Appeleztools/listpour la surface actuelle.agent-browser— un CLI qui pilote un vrai Chrome. Connaît des éléments navigateur indépendants du framework : DOM, console, réseau, fibre React, métriques vitales. Avant de l'utiliser, exécutezagent-browser skills get coreune fois pour obtenir le guide d'utilisation correspondant à votre version — ne devinez pas les sous-commandes de mémoire.
Les deux vues se recoupent mutuellement.
prérequis
- Next.js 16.3+ avec Turbopack —
/_next/mcpplus la vérification proactive de compilation viaget_compilation_issues. agent-browser>= 0.31.1 — introspection React,session idlimité à l'arbre de travail,--restoreidempotent et réconciliation des indicateurs de lancement.
Ce sont des seuils minimums stricts, pas des préférences souples. Si quelque chose manque, dites à l'utilisateur comment mettre à niveau et arrêtez-vous. Ne revenez pas à la recherche dans le code source ou à une sonde plus faible — cette compétence suppose que les deux vues sont actives aux versions ci-dessus.
- Mettre à niveau Next.js :
pnpm next upgrade(ounpx next upgrade). Documentation : https://nextjs.org/docs/app/getting-started/upgrading (Guide version 16 : https://nextjs.org/docs/app/guides/upgrading/version-16) - Installer ou mettre à niveau
agent-browser:npm i -g agent-browser@latest. Si le CLI n'est pas dans lePATH, installez-le avant de continuer — la vérification préliminaire s'attend à l'invoquer directement.
pré-vol
Une fois par session, confirmez que les deux vues sont actives.
-
Ouvrez
agent-browserà l'URL cible, en restaurant l'état de connexion sauvegardé lorsqu'il est présent. Commencez par dériver un identifiant de session stable pour cette copie de travail et utilisez-le pour chaque commandeagent-browser:SESSION="$(agent-browser session id --scope worktree --prefix next-dev-loop)" export AGENT_BROWSER_SESSION="$SESSION" export AGENT_BROWSER_RESTORE="$SESSION"Ouvrez ensuite l'URL cible :
agent-browser --session "$SESSION" --restore --headed --enable react-devtools open <url>--scope worktreeempêche les arbres de travail parallèles et les copies de checkout de se chevaucher.--restoreseul utilise l'identifiant de session comme clé de persistance, charge les cookies/localStorage sauvegardés avant la navigation lorsqu'ils sont présents, et sauvegarde automatiquement l'état à la fermeture. Passez toujours les indicateurs de lancement souhaités suropen; agent-browser réutilisera, relancera ou redémarrera son état d'arrière-plan limité selon les besoins.Le navigateur est celui de l'utilisateur. Si l'état n'a pas été restauré (première exécution, session expirée) et que la page est protégée, l'utilisateur effectue la connexion — faites une pause jusqu'à ce qu'il confirme. Après la connexion, continuez à utiliser la même session et le contexte de restauration ;
agent-browser closesauvegarde l'état des cookies afin que la prochaineopenle restaure. -
Sondez
/_next/mcp(tools/list) — confirmez qu'il est joignable et qu'il listeget_compilation_issues:- Injoignable → soit
next devn'est pas en cours d'exécution, soit Next.js est antérieur à la version 16.3. Vérifiezpackage.jsonpour lever l'ambiguïté, puis refusez. get_compilation_issuesn'est pas dans la liste → Next.js antérieur à 16.3. Refusez et dites à l'utilisateur de mettre à niveau.
- Injoignable → soit
-
get_compilation_issuessert également de sonde Turbopack. Une réponse d'erreur"Turbopack project is not available..."signifie que l'utilisateur est sur webpack. Refusez — Turbopack est requis. -
get_routes→ votre carte des routes pour le reste de la session.
boucle
avant la modification — réduisez le périmètre
Interrogez l'application en cours d'exécution, pas la base de code. /_next/mcp sait
quels fichiers ont rendu la route actuelle ; utilisez-les comme périmètre de recherche.
L'introspection runtime reste économique à mesure que la base de code grandit ; la recherche
agentique ne l'est pas.
après la modification — vérifiez
Quatre modes d'échec. Vérifiez chacun :
- Compilation —
get_compilation_issues. - Exécution sans erreurs —
/_next/mcp(les erreurs serveur et les erreurs navigateur remontées apparaissent ici). - Comportement conforme —
agent-browserpilote la page ; affirmez ce que l'utilisateur voit réellement. - Comportement au niveau React —
agent-browseravec react-devtools activé expose l'arbre des composants, les props, l'état et les compteurs de rendu. Ancrez ici les vérifications au niveau du framework (rendus supplémentaires, déplacements de frontière serveur/client, fallbacks suspense) — les assertions DOM seules les manquent.
Choisissez l'outil spécifique dans tools/list ou le manuel
agent-browser plutôt que de mémoire.
pièges
- Chaque commande
agent-browserdoit connaître votre session et votre clé de restauration, sinon elle pourrait utiliser un navigateur par défaut vide ou échouer à sauvegarder l'état de connexion. Le plus simple : exportez à la foisAGENT_BROWSER_SESSION="$SESSION"etAGENT_BROWSER_RESTORE="$SESSION"en haut de chaque terminal où vous exécutez agent-browser. Si vous ne les exportez pas, passez--session "$SESSION" --restoresur chaque commande. - Quand les deux vues divergent, suspectez d'abord l'outillage. Si
agent-browserindique qu'une route est cassée mais que/_next/mcpet le serveur disent qu'elle a été rendue proprement, une session navigateur obsolète ou mal dirigée est plus probable qu'un vrai bogue — réconciliez les vues avant de déboguer l'application. - Confirmer un clic ou une navigation : la page se stabilise un instant plus tard, donc
attendez avec
wait --load networkidle(pas de chemin à se tromper), puis prenez un instantané/lisez pour confirmer la page. Évitezwait --urlsauf si vous passez le href exact du lien — un chemin deviné ou un espace réservé ne correspondra pas à l'URL réelle et expirera après 25s. - Une lecture vide, un instantané vide,
about:blankou une erreur "no browser session" — juste aprèsopenou après un clic (même siopena signalé la page) — signifie que le navigateur a abandonné la page (une session obsolète), pas une route cassée. Rouvrez votre session à l'URL avec--session "$SESSION" --restoreet reprenez un instantané ; si toujours vide, exécutezagent-browser --session "$SESSION" --restore close, puis ouvrez à nouveau. Ne revenez pas àcurl; il contourne le navigateur que vous testez. - Le résultat de l'introspection React est obsolète après une navigation. Réexécutez.
- Les réponses de
/_next/mcpsont SSE — lisez le JSON de la lignedata:avecsed -n 's/^data: //p'(un simplesed 's/^data: //'laisse la ligneevent:et l'analyse échoue). - Serveur de développement non sur le port 3000 : lisez la bannière
next dev; définissezNEXT_MCP_URL=http://localhost:<port>/_next/mcp. get_errorsetget_page_metadatanécessitent au moins une navigation pour se remplir.
référence
Tous les outils ci-dessous sont présents une fois le pré-vol réussi. Si tools/list
manque de l'un d'eux, le pré-vol aurait dû refuser — revérifiez.
# /_next/mcp notes
get_project_metadata projectPath, devServerUrl, bundler
get_routes analyse du système de fichiers ; aucune session navigateur nécessaire
get_errors runtime + compilation ; nécessite une session navigateur ;
inclut les erreurs côté navigateur interceptées par le
serveur de développement
get_page_metadata trie de segments + routerType ; nécessite une session
navigateur ; utilisez-le comme raccourci de découverte pour
savoir quels fichiers alimentent une route
get_logs renvoie logFilePath
get_server_action_by_id id haché → fichier + nomFonction
get_compilation_issues Turbopack uniquement ; erreurs sur webpack
("Turbopack project is not available")
démontage
Fermez la session avec le même contexte de session et de restauration :
agent-browser --session "$SESSION" --restore close. close sauvegarde
les cookies et le stockage de cette session afin que la prochaine open avec --restore garde
l'utilisateur connecté. Laissez next dev en cours pour la prochaine boucle.
Les jumeaux next-dev-loop-<sujet> (par exemple next-dev-loop-rsc, next-dev-loop-debug)
supposent que ce pré-vol a déjà été exécuté ; ils reprennent à la boucle.