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.

Open
agent-browser
at the target URL, restoring saved login state when present. Build the
```
open
```
command from:
- ```
--session-name <slug>
```
  where
```
<slug>
```
  is the project directory basename.
- ```
--state ~/.agent-browser/sessions/<slug>-default.json
```
  if that file exists. Omit on first run — a missing path fails the open.
- ```
--headed --enable react-devtools
```
  .
The browser is the user's. If state was not restored (first run, expired session) and the page is gated, the user drives the login — pause until they confirm. Session state is sticky: 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/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.
```
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.
```
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

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 —

--session-name

writes state to disk so the next loop's

--state

restores login. 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.

next-dev-loop

NPX Install

Tags

SKILL.md Content

next-dev-loop

requires

preflight

loop

before the edit — narrow the scope

after the edit — verify

gotchas

reference

teardown