Skill v1.0.0
currentTrusted Publisher100/100version: "1.0.0" 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/mcpplus 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(ornpx 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.
- **Open the user's
agent-browsersession 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.
- POST
tools/listto/_next/mcp. Send
Accept: application/json, text/event-stream; responses are SSE-framed, strip the data: prefix before parsing JSON.
- Unreachable → either
next devisn't running, or Next.js is
below 16.3. Check package.json to disambiguate, then refuse.
get_compilation_issuesnot in the list → Next.js below 16.3.
Refuse and tell the user to upgrade.
mcp get_compilation_issuesdoubles as a Turbopack probe.
An error response of "Turbopack project is not available..." means the user is on webpack. Refuse — Turbopack is required.
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-browserdrives the page; assert
what the user actually sees.
- React-level behavior —
agent-browserwith 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 devbanner; set
NEXT_MCP_URL=http://localhost:<port>/_next/mcp.
get_errorsandget_page_metadataneed 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 notesget_project_metadata projectPath, devServerUrl, bundlerget_routes fs-scan; no browser session neededget_errors runtime + build; needs a browser session;includes browser-side errors caught by thedev serverget_page_metadata segment trie + routerType; needs a browsersession; use as a discovery shortcut forwhich files power a routeget_logs returns logFilePathget_server_action_by_id hashed id → file + functionNameget_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.