Back to Details

next-dev-loop

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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. Run 
    agent-browser --help
    for the current surface.
The two views cross-check each other.
next dev
过程中的编辑/验证流程——做出变更后，确认其在运行时实际生效，而非仅通过类型检查或构建。
你可以通过运行中应用的两个视角进行验证：
  • /_next/mcp
     — Next.js暴露的一个HTTP端点，包含框架专属信息：路由、分段、RSC、服务器操作、服务器日志以及Next.js捕获的错误。调用
    tools/list
    可查看当前可用功能。
  • agent-browser
     — 驱动真实Chrome浏览器的CLI工具，支持与框架无关的浏览器相关操作：DOM、控制台、网络、React Fiber、性能指标。运行
    agent-browser --help
    可查看当前可用功能。
这两个视角可以互相交叉验证。

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.
  • 搭载Turbopack的Next.js **16.3+**版本——支持
    /_next/mcp
    以及通过
    get_compilation_issues
    进行主动编译检查。
  • agent-browser
    >= 0.27.0版本——此版本引入了React自省功能。
这些是硬性要求，而非可选配置。若缺少任一组件，请告知用户升级方法并终止流程。不要退回到搜索源码或使用更弱的探测方式——此技能假设上述版本的两个视角均已启用。

preflight

预检查

Once per session, confirm both views are live.
  1. 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.
  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.
每次会话开始时，需确认两个视角均已启用。
  1. 在目标URL打开
    agent-browser
    ，如有保存的登录状态则恢复。     构建
    open
    命令需包含：
    • --session-name <slug>
      ，其中
      <slug>
      为项目目录的基础名称。
    • 若文件存在，添加
      --state ~/.agent-browser/sessions/<slug>-default.json
      ；首次运行时省略——路径不存在会导致打开失败。
    • --headed --enable react-devtools
      。
    浏览器归用户所有。若未恢复状态（首次运行或会话过期）且页面需要登录，由用户完成登录操作——等待用户确认后再继续。会话状态是固定的：会话打开后无法添加
    --enable react-devtools
    ，且在会话未打开时设置
    cookies set
    会创建无会话的cookie，导致无法生效。
  2. 向
    /_next/mcp
    发送POST请求
    tools/list
    。请求头设置
    Accept: application/json, text/event-stream
    ；响应为SSE格式，解析JSON前需移除
    data:
    前缀。
    • 无法访问 → 要么
      next dev
      未运行，要么Next.js版本低于16.3。检查
      package.json
      以区分情况，然后拒绝继续。
    • 列表中无
      get_compilation_issues
      → Next.js版本低于16.3。拒绝继续并告知用户升级。
  3. mcp get_compilation_issues
    同时可作为Turbopack探测工具。若返回错误
    "Turbopack project is not available..."
    ，说明用户使用的是webpack。拒绝继续——必须使用Turbopack。
  4. mcp get_routes
    → 获取后续会话所需的路由映射。

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.
向运行中的应用查询，而非代码库。
/_next/mcp
知晓当前路由对应的渲染文件；将这些文件作为搜索范围。运行时自省在代码库扩大时仍能保持高效，而智能搜索则不行。

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.
四种失败模式，需逐一检查：
  • 编译通过 — 
    mcp get_compilation_issues
    。
  • 运行无错误 — 
    /_next/mcp
    （服务器和冒泡上来的浏览器错误都会在此显示）。
  • 行为符合预期 — 
    agent-browser
    驱动页面，验证用户实际看到的内容。
  • React层面行为 — 启用react-devtools的
    agent-browser
    可展示组件树、props、state以及渲染次数。在此进行框架层面的检查（额外渲染、服务端/客户端边界变化、suspense回退）——仅DOM断言会遗漏这些问题。
从
tools/list
或
agent-browser --help
中选择具体工具，而非凭记忆调用。

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.
  • 导航后React自省输出会过时，需重新运行。
  • 非3000端口的开发服务器：查看
    next dev
    启动横幅；设置
    NEXT_MCP_URL=http://localhost:<port>/_next/mcp
    。
  • get_errors
    和
    get_page_metadata
    需要至少一次导航才能填充数据。

reference

参考

All tools below are present once preflight passes. If 
tools/list
is missing any of them, preflight should have refused — re-check.
undefined
预检查通过后，以下所有工具均可用。若
tools/list
中缺少任一工具，预检查应已拒绝继续——请重新检查。
undefined

/_next/mcp notes

/_next/mcp 说明

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")
undefined
get_project_metadata 项目路径、开发服务器URL、打包工具 get_routes 文件系统扫描；无需浏览器会话 get_errors 运行时+构建错误；需要浏览器会话；包含开发服务器捕获的浏览器端错误 get_page_metadata 分段字典树+路由类型；需要浏览器会话；可快速发现路由对应的文件 get_logs 返回日志文件路径 get_server_action_by_id 哈希ID → 文件+函数名 get_compilation_issues 仅支持Turbopack；使用webpack时会报错（"Turbopack project is not available"）
undefined

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.
关闭
agent-browser
会话——
--session-name
会将状态写入磁盘，以便下一次循环通过
--state
恢复登录状态。保持
next dev
运行，供下一次循环使用。
next-dev-loop-<topic>
系列技能（如
next-dev-loop-rsc
、
next-dev-loop-debug
）假设已完成此预检查流程，它们直接从循环阶段开始执行。",