next-dev-loop

name	next-dev-loop
description	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`.

next-dev-loop

The edit/verify rhythm during next dev — make a change, then confirm it actually works at runtime, not only that the types or the build are happy.

You verify through two views of the same running app:

• /_next/mcp — an HTTP endpoint Next.js exposes about itself. Knows framework-specific things: routes, segments, RSC, server actions, server logs, and errors as Next.js saw them. Call tools/list for the current surface.
• agent-browser — a CLI that drives a real Chrome. Knows framework-agnostic browser things: DOM, console, network, React fiber, vitals. Run agent-browser --help for the current surface.

The two views cross-check each other.

requires

• Next.js 16.3+ with Turbopack — /_next/mcp plus the proactive compile check via get_compilation_issues.
• agent-browser >= 0.27.0 — when React introspection landed.

These are hard floors, not soft preferences. If anything is missing, tell the user how to upgrade and stop. Don't fall back to grepping source or to a weaker probe — this skill assumes both views are live at the versions above.

• Upgrade Next.js: pnpm next upgrade (or npx next upgrade). Docs: https://nextjs.org/docs/app/getting-started/upgrading (version-16 guide: https://nextjs.org/docs/app/guides/upgrading/version-16)
• Upgrade agent-browser: npm i -g agent-browser@latest.

preflight

Once per session, confirm both views are live.

1. Open the user's agent-browser session at the target URL with --headed and react-devtools enabled, then pause. The browser is the user's, not yours; agent-browser open is headless by default, so --headed is required. If the page is behind login, gated by a feature flag, or needs specific state, the user drives that — log in, set state, navigate. Continue only after they confirm. Session state is sticky per session: you can't add --enable react-devtools after the session is open, and cookies set on a not-yet-opened session creates a sessionless cookie that silently fails to apply.
2. POST tools/list to /_next/mcp. Send Accept: application/json, text/event-stream; responses are SSE-framed, strip the data: prefix before parsing JSON.
   • Unreachable → either next dev isn't running, or Next.js is below 16.3. Check package.json to disambiguate, then refuse.
   • get_compilation_issues not in the list → Next.js below 16.3. Refuse and tell the user to upgrade.
3. mcp get_compilation_issues doubles as a Turbopack probe. An error response of "Turbopack project is not available..." means the user is on webpack. Refuse — Turbopack is required.
4. mcp get_routes → your route map for the rest of the session.

loop

before the edit — narrow the scope

Ask the running app, not the codebase. /_next/mcp knows which files rendered the current route; use those as your search scope. Runtime introspection stays cheap as the codebase grows; agentic search doesn't.

after the edit — verify

Four failure modes. Check each:

• Compiles — mcp get_compilation_issues.
• Runs without errors — /_next/mcp (server and bubbled-up browser errors both surface here).
• Behaves as intended — agent-browser drives the page; assert what the user actually sees.
• React-level behavior — agent-browser with react-devtools enabled exposes the component tree, props, state, and render counts. Anchor framework-level checks here (extra renders, server/client boundary shifts, suspense fallbacks) — DOM asserts alone miss them.

Pick the specific tool from tools/list or agent-browser --help rather than from memory.

gotchas

• React introspection output is stale after navigation. Re-run.
• Non-3000 dev server: read the next dev banner; set NEXT_MCP_URL=http://localhost:<port>/_next/mcp.
• get_errors and get_page_metadata need at least one navigation to populate.

reference

All tools below are present once preflight passes. If tools/list is missing any of them, preflight should have refused — re-check.

# /_next/mcp                 notes
get_project_metadata         projectPath, devServerUrl, bundler
get_routes                   fs-scan; no browser session needed
get_errors                   runtime + build; needs a browser session;
                             includes browser-side errors caught by the
                             dev server
get_page_metadata            segment trie + routerType; needs a browser
                             session; use as a discovery shortcut for
                             which files power a route
get_logs                     returns logFilePath
get_server_action_by_id      hashed id → file + functionName
get_compilation_issues       Turbopack only; errors on webpack
                             ("Turbopack project is not available")

teardown

Close the agent-browser session. Leave next dev up for the next loop.

---

next-dev-loop-<topic> siblings (e.g. next-dev-loop-rsc, next-dev-loop-debug) assume this preflight already ran; they pick up at the loop.