Next Dev Loop

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. Before driving it, run agent-browser skills get core once for the version-matched usage guide — don't guess subcommands from memory.

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.31.1 — React introspection, worktree-scoped session id, idempotent --restore, and launch flag reconciliation.

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)
• Install or upgrade agent-browser: npm i -g agent-browser@latest. If the CLI isn't on PATH, install it before continuing — preflight expects to invoke it directly.

preflight

Once per session, confirm both views are live.

1. Open agent-browser at the target URL, restoring saved login state when present. First derive one stable session id for this checkout and use it for every agent-browser command:

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

   Then open the target URL:

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

   --scope worktree keeps parallel worktrees and copied checkouts from colliding. Bare --restore uses the session id as the persistence key, loads saved cookies/localStorage before navigation when present, and auto-saves state on close. Always pass the desired launch flags on open; agent-browser will reuse, relaunch, or restart its scoped background state as needed.

   Keep routine verification headless. If the user asks to see the UI, open the current URL in the coding harness's inline browser. It is a separate browser context, so do not assume state carries over. When login or existing agent-browser state must carry over, reopen that session headed instead:

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

   Pause while the user drives login, then continue with the same session and keep it headed for the rest of the loop.

2. Probe /_next/mcp (tools/list) — confirm it's reachable and lists get_compilation_issues. First read the port off the next dev banner; if it isn't 3000, set NEXT_MCP_URL=http://localhost:<port>/_next/mcp before probing:

   • 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. 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. 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 — 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 the agent-browser manual rather than from memory.