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.
preflight
Once per session, confirm both views are live.
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 --headed --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.
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. After login, continue using the same session
and restore context; agent-browser close saves the cookie state so
the next open restores it.
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.
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.
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.
gotchas
- Preserve
.next while the development server is running. Moving or
deleting it disconnects the server from its generated state and discards
incremental caches. Moving it to a backup is still a reset. If a production
build needs isolated output, configure a separate distDir.
- Every
agent-browser command must know your session and restore
key, or it may use an empty default browser or fail to save login
state. Easiest: export both AGENT_BROWSER_SESSION="$SESSION" and
AGENT_BROWSER_RESTORE="$SESSION" at the top of each shell you run
agent-browser in. If you do not export them, pass
--session "$SESSION" --restore on every command.
- When the two views disagree, suspect the tooling first. If
agent-browser says a route is broken but /_next/mcp and the
server say it rendered cleanly, a stale or misdirected browser
session is the likelier cause than a real bug — reconcile the views
before debugging the app.
- Confirming a click or navigation: the page settles a beat later, so
wait with
wait --load networkidle (no path to get wrong), then
snapshot/read to confirm the page. Avoid wait --url unless you pass
the link's exact href — a guessed or placeholder path won't match the
real URL and times out after 25s.
- A blank read, empty snapshot,
about:blank, or a "no browser
session" error — right after open or after a click (even if open
reported the page) — is the browser dropping the page (a stale
session), not a broken route. Reopen your session at the URL with
--session "$SESSION" --restore and re-snapshot; if still blank,
run agent-browser --session "$SESSION" --restore close, then open
again. Don't fall back to curl; it bypasses the browser you're
testing.
- React introspection output is stale after navigation. Re-run.
/_next/mcp replies are SSE — read the JSON off the data: line
with sed -n 's/^data: //p' (a plain sed 's/^data: //' leaves the
event: line and the parse fails).
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 session with the same session and restore context:
agent-browser --session "$SESSION" --restore close. close saves
that session's cookies and storage so the next loop's --restore open
keeps the user logged in. Leave next dev up for the next loop.
1---
2name: next-dev-loop
3description: >
4 Verify Next.js runtime behavior after editing app code. Use this
5 skill to confirm a change actually works in a running app — not
6 just that it compiles or type-checks. Combines /_next/mcp
7 (Next.js's view) with agent-browser (the browser's view).
8 Requires a running `next dev`.
9metadata:
10 source: https://skillmd.com/skills/vercel/next-dev-loop
11---
12
13# next-dev-loop
14
15The edit/verify rhythm during `next dev` — make a change, then
16confirm it actually works at runtime, not only that the types or
17the build are happy.
18
19You verify through two views of the same running app:
20
21- **`/_next/mcp`** — an HTTP endpoint Next.js exposes about itself.
22 Knows framework-specific things: routes, segments, RSC, server
23 actions, server logs, and errors as Next.js saw them. Call
24 `tools/list` for the current surface.
25- **`agent-browser`** — a CLI that drives a real Chrome. Knows
26 framework-agnostic browser things: DOM, console, network, React
27 fiber, vitals. Before driving it, run `agent-browser skills get core`
28 once for the version-matched usage guide — don't guess subcommands
29 from memory.
30
31The two views cross-check each other.
32
33## requires
34
35- Next.js **16.3+** with **Turbopack** — `/_next/mcp` plus the
36 proactive compile check via `get_compilation_issues`.
37- `agent-browser` **>= 0.31.1** — React introspection, worktree-scoped
38 `session id`, idempotent `--restore`, and launch flag reconciliation.
39
40These are hard floors, not soft preferences. If anything is missing,
41tell the user how to upgrade and stop. Don't fall back to grepping
42source or to a weaker probe — this skill assumes both views are live
43at the versions above.
44
45- Upgrade Next.js: `pnpm next upgrade` (or `npx next upgrade`).
46 Docs: https://nextjs.org/docs/app/getting-started/upgrading
47 (version-16 guide:
48 https://nextjs.org/docs/app/guides/upgrading/version-16)
49- Install or upgrade `agent-browser`: `npm i -g agent-browser@latest`.
50 If the CLI isn't on `PATH`, install it before continuing — preflight
51 expects to invoke it directly.
52
53## preflight
54
55Once per session, confirm both views are live.
56
571. **Open `agent-browser` at the target URL, restoring saved
58 login state when present.** First derive one stable session id for
59 this checkout and use it for every `agent-browser` command:
60
61 ```bash
62 SESSION="$(agent-browser session id --scope worktree --prefix next-dev-loop)"
63 export AGENT_BROWSER_SESSION="$SESSION"
64 export AGENT_BROWSER_RESTORE="$SESSION"
65 ```
66
67 Then open the target URL:
68
69 ```bash
70 agent-browser --session "$SESSION" --restore --headed --enable react-devtools open <url>
71 ```
72
73 `--scope worktree` keeps parallel worktrees and copied checkouts
74 from colliding. Bare `--restore` uses the session id as the
75 persistence key, loads saved cookies/localStorage before navigation
76 when present, and auto-saves state on close. Always pass the desired
77 launch flags on `open`; agent-browser will reuse, relaunch, or restart
78 its scoped background state as needed.
79
80 The browser is the user's. If state was not restored (first run,
81 expired session) and the page is gated, the user drives the login —
82 pause until they confirm. After login, continue using the same session
83 and restore context; `agent-browser close` saves the cookie state so
84 the next `open` restores it.
85
862. Probe `/_next/mcp` (`tools/list`) — confirm it's reachable and
87 lists `get_compilation_issues`. First read the port off the
88 `next dev` banner; if it isn't 3000, set
89 `NEXT_MCP_URL=http://localhost:<port>/_next/mcp` before probing:
90 - Unreachable → either `next dev` isn't running, or Next.js is
91 below 16.3. Check `package.json` to disambiguate, then refuse.
92 - `get_compilation_issues` not in the list → Next.js below 16.3.
93 Refuse and tell the user to upgrade.
943. `get_compilation_issues` doubles as a Turbopack probe. An error
95 response of `"Turbopack project is not available..."` means the
96 user is on webpack. Refuse — Turbopack is required.
974. `get_routes` → your route map for the rest of the session.
98
99## loop
100
101### before the edit — narrow the scope
102
103Ask the running app, not the codebase. `/_next/mcp` knows which
104files rendered the current route; use those as your search scope.
105Runtime introspection stays cheap as the codebase grows; agentic
106search doesn't.
107
108### after the edit — verify
109
110Four failure modes. Check each:
111
112- **Compiles** — `get_compilation_issues`.
113- **Runs without errors** — `/_next/mcp` (server and bubbled-up
114 browser errors both surface here).
115- **Behaves as intended** — `agent-browser` drives the page; assert
116 what the user actually sees.
117- **React-level behavior** — `agent-browser` with react-devtools
118 enabled exposes the component tree, props, state, and render
119 counts. Anchor framework-level checks here (extra renders,
120 server/client boundary shifts, suspense fallbacks) — DOM asserts
121 alone miss them.
122
123Pick the specific tool from `tools/list` or the agent-browser
124manual rather than from memory.
125
126## gotchas
127
128- **Preserve `.next` while the development server is running.** Moving or
129 deleting it disconnects the server from its generated state and discards
130 incremental caches. Moving it to a backup is still a reset. If a production
131 build needs isolated output, configure a separate `distDir`.
132- **Every `agent-browser` command must know your session and restore
133 key, or it may use an empty default browser or fail to save login
134 state.** Easiest: export both `AGENT_BROWSER_SESSION="$SESSION"` and
135 `AGENT_BROWSER_RESTORE="$SESSION"` at the top of each shell you run
136 agent-browser in. If you do not export them, pass
137 `--session "$SESSION" --restore` on every command.
138- **When the two views disagree, suspect the tooling first.** If
139 `agent-browser` says a route is broken but `/_next/mcp` and the
140 server say it rendered cleanly, a stale or misdirected browser
141 session is the likelier cause than a real bug — reconcile the views
142 before debugging the app.
143- Confirming a click or navigation: the page settles a beat later, so
144 wait with `wait --load networkidle` (no path to get wrong), then
145 snapshot/read to confirm the page. Avoid `wait --url` unless you pass
146 the link's exact href — a guessed or placeholder path won't match the
147 real URL and times out after 25s.
148- A blank read, empty snapshot, `about:blank`, or a "no browser
149 session" error — right after `open` or after a click (even if `open`
150 reported the page) — is the browser dropping the page (a stale
151 session), not a broken route. Reopen your session at the URL with
152 `--session "$SESSION" --restore` and re-snapshot; if still blank,
153 run `agent-browser --session "$SESSION" --restore close`, then open
154 again. Don't fall back to `curl`; it bypasses the browser you're
155 testing.
156- React introspection output is stale after navigation. Re-run.
157- `/_next/mcp` replies are SSE — read the JSON off the `data:` line
158 with `sed -n 's/^data: //p'` (a plain `sed 's/^data: //'` leaves the
159 `event:` line and the parse fails).
160- `get_errors` and `get_page_metadata` need at least one navigation
161 to populate.
162
163## reference
164
165All tools below are present once preflight passes. If `tools/list`
166is missing any of them, preflight should have refused — re-check.
167
168```
169# /_next/mcp notes
170get_project_metadata projectPath, devServerUrl, bundler
171get_routes fs-scan; no browser session needed
172get_errors runtime + build; needs a browser session;
173 includes browser-side errors caught by the
174 dev server
175get_page_metadata segment trie + routerType; needs a browser
176 session; use as a discovery shortcut for
177 which files power a route
178get_logs returns logFilePath
179get_server_action_by_id hashed id → file + functionName
180get_compilation_issues Turbopack only; errors on webpack
181 ("Turbopack project is not available")
182```
183
184## teardown
185
186Close the session with the same session and restore context:
187`agent-browser --session "$SESSION" --restore close`. `close` saves
188that session's cookies and storage so the next loop's `--restore` open
189keeps the user logged in. Leave `next dev` up for the next loop.