Communitygithub.com

next-dev-loop

在編輯應用程式代碼後驗證 Next.js 執行時行為。使用此技能確認變更確實能在運行中的應用程式內生效,而不僅僅是編譯或型別檢查通過。結合 /_next/mcp (Next.js 的視角) 與 agent-browser (瀏覽器的視角)。需要正在運行的 next dev。

next-dev-loop 是什麼?

這項技能 (next-dev-loop) 專為在使用 Next.js 進行開發時實現高效的編輯/驗證循環而設計。它通過兩個互補的視角來強制進行執行時驗證:一個是 Next.js 框架自身的 /_next/mcp HTTP 端點,另一個是 agent-browser 命令列工具。其核心目標是確保每項變更不僅在編譯階段通過,在實際的瀏覽器運行環境中也能正常工作,從而消除開發者的猜疑。使用者需要安裝指定的 Next.js 版本 (16.3+) 與 agent-browser (>= 0.31.1) 版本,並在啟動循環前完成一次性的預檢流程 (preflight) 來設定瀏覽器 session 和確認 MCP 端點可用。該技能詳細說明了四個驗證階段 (編譯、執行錯誤、行為、React層級),並提供了處理常見問題 (如 session 過期、頁面空白、SSE 回應解析) 的明確指引。最後,它會透過關閉會話來保存登入狀態,以供後續開發循環使用,並為更進階的主題 (如 RSC、除錯) 提供了基礎架構。

相容平台~Claude Code~Codex CLI~Cursor✓Antigravity
npx skills add https://github.com/0n6k4v-Coder/skills/tree/HEAD/next.js/next-dev-loop

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

next-dev-loop 是做什麼的?

在 next dev 期間的編輯/驗證節奏 — 進行變更,然後 確認它在執行時實際有效,而不僅僅是型別或建置通過。

您可以透過同一個運行中應用程式的兩個視角進行驗證:

  • /_next/mcp — Next.js 公開的 HTTP 端點,用於描述自身。 瞭解框架特定的項目:路由、區段、RSC、伺服器 動作、伺服器日誌,以及 Next.js 所看到的錯誤。呼叫 tools/list 取得目前的可用工具清單。
  • agent-browser — 一個驅動真實 Chrome 的 CLI。瞭解 與框架無關的瀏覽器事物:DOM、控制台、網路、React fiber、效能指標。在驅動它之前,請先執行 agent-browser skills get core 一次,以取得與版本匹配的使用指南 — 不要憑記憶猜測子命令。

這兩個視角會互相驗證。

需求

  • Next.js 16.3+ 搭配 Turbopack — /_next/mcp 加上 透過 get_compilation_issues 進行的主動編譯檢查。
  • agent-browser >= 0.31.1 — React 內省、工作樹範圍的 session id、冪等的 --restore,以及啟動標誌協調。

這些是硬性下限,不是軟性偏好。如果缺少任何項目, 請告訴使用者如何升級並停止。不要退而求其次去搜尋原始碼 或使用較弱的探測 — 此技能假設兩個視角都以上述 版本在運行。

預檢

在每個工作階段執行一次,確認兩個視角都在運行中。

  1. 在目標 URL 開啟 agent-browser,並在存在時還原已儲存的 登入狀態。 首先為此程式碼庫推導出一個穩定的 session id, 並在每個 agent-browser 命令中使用它:

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

    然後開啟目標 URL:

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

    --scope worktree 可防止平行 worktree 和複製的 checkout 發生碰撞。單純的 --restore 使用 session id 作為 持久化金鑰,在導航前載入已儲存的 cookies/localStorage(如果存在), 並在關閉時自動儲存狀態。始終在 open 命令上傳遞所需的 啟動標誌;agent-browser 將根據需要重複使用、重新啟動或重啟 其範圍內的背景狀態。

    瀏覽器是使用者的。如果狀態未還原(首次執行、 session 過期)且頁面需要登入,由使用者驅動登入 — 暫停直到他們確認。登入後,繼續使用同一個 session 和 restore 上下文;agent-browser close 會儲存 cookie 狀態, 以便下次 open 還原它。

  2. 探測 /_next/mcp (tools/list) — 確認它可以訪問並且 列出了 get_compilation_issues:

    • 無法訪問 → 可能是 next dev 未運行,或是 Next.js 低於 16.3。檢查 package.json 以釐清,然後拒絕。
    • get_compilation_issues 不在清單中 → Next.js 低於 16.3。 拒絕並告訴使用者升級。
  3. get_compilation_issues 同時兼作 Turbopack 探測。一個 錯誤回應 "Turbopack project is not available..." 表示 使用者正在使用 webpack。拒絕 — 需要 Turbopack。

  4. get_routes → 取得您在工作階段剩餘時間內的路由映射。

循環

編輯前 — 縮小範圍

詢問正在運行的應用程式,而不是程式碼庫。/_next/mcp 知道 哪些檔案渲染了目前路由;將這些作為您的搜尋範圍。 隨著程式碼庫增長,執行時期內省仍然廉價; 自主搜尋則不然。

編輯後 — 驗證

四種失敗模式。逐一檢查:

  • 編譯 — get_compilation_issues。
  • 執行無錯誤 — /_next/mcp(伺服器錯誤和冒泡上來的 瀏覽器錯誤都會在此顯示)。
  • 行為如預期 — agent-browser 驅動頁面;斷言 使用者實際看到的內容。
  • React 層級行為 — agent-browser 啟用 react-devtools 後,可以暴露元件樹、props、state 和渲染 計數。在此錨定框架層級的檢查(額外渲染、 伺服器/客戶端邊界變動、Suspense fallback)— 僅靠 DOM 斷言 會遺漏它們。

從 tools/list 或 agent-browser 手冊中選擇特定的工具,而不是憑記憶。

注意事項

  • 每個 agent-browser 命令都必須知道您的 session 和 restore 金鑰,否則它可能會使用空的預設瀏覽器或無法儲存登入 狀態。 最簡單的方法:在您運行 agent-browser 的每個 shell 頂部 同時匯出 AGENT_BROWSER_SESSION="$SESSION" 和 AGENT_BROWSER_RESTORE="$SESSION"。如果您不匯出它們, 請在每個命令上傳遞 --session "$SESSION" --restore。
  • 當兩個視角不一致時,首先懷疑工具本身。 如果 agent-browser 說路由壞了,但 /_next/mcp 和伺服器 說它渲染無誤,那麼過時或錯誤導向的瀏覽器 session 比真正的錯誤更可能是原因 — 在除錯應用程式之前, 先調和這兩個視角。
  • 確認點擊或導航:頁面會稍後才穩定下來,因此 使用 wait --load networkidle(沒有可能會搞錯的路徑)等待, 然後快照/讀取以確認頁面。避免使用 wait --url,除非您傳遞 連結的確切 href — 猜測或佔位符路徑不會匹配 真實 URL,並會在 25 秒後超時。
  • 空白讀取、空快照、about:blank 或 "no browser session" 錯誤 — 可能在 open 之後或點擊之後(即使 open 回報了頁面)— 是瀏覽器丟棄了頁面(過期的 session),而不是路由壞了。使用 --session "$SESSION" --restore 在該 URL 重新開啟您的 session 並重新快照;如果仍然是空白, 執行 agent-browser --session "$SESSION" --restore close,然後再次 開啟。不要退而求其次使用 curl;它繞過了您正在測試的 瀏覽器。
  • React 內省輸出在導航後會過時。請重新執行。
  • /_next/mcp 回覆是 SSE — 使用 sed -n 's/^data: //p' 從 data: 行 讀取 JSON(單純的 sed 's/^data: //' 會留下 event: 行 導致解析失敗)。
  • 非 3000 埠的開發伺服器:讀取 next dev 橫幅;設定 NEXT_MCP_URL=http://localhost:<port>/_next/mcp。
  • get_errors 和 get_page_metadata 需要至少一次導航 才能填充資料。

參考

一旦預檢通過,以下所有工具都應存在。如果 tools/list 缺少其中任何一個,預檢應該已經拒絕 — 請重新檢查。

# /_next/mcp                 備註
get_project_metadata         projectPath, devServerUrl, bundler
get_routes                   檔案系統掃描;不需要瀏覽器 session
get_errors                   執行時 + 建置;需要瀏覽器 session;
                             包含開發伺服器捕獲的瀏覽器端錯誤
get_page_metadata            區段 Trie + routerType;需要瀏覽器
                             session;用作發現哪個檔案驅動路由的快捷方式
get_logs                     回傳 logFilePath
get_server_action_by_id      雜湊 id → 檔案 + functionName
get_compilation_issues       僅限 Turbopack;webpack 上會報錯
                             ("Turbopack project is not available")

結束

使用相同的 session 和 restore 上下文關閉 session: agent-browser --session "$SESSION" --restore close。close 會儲存 該 session 的 cookies 和儲存空間,以便下次循環的 --restore open 讓使用者保持登入狀態。讓 next dev 保持運行以備下次循環使用。


next-dev-loop-<主題> 的兄弟技能(例如 next-dev-loop-rsc、next-dev-loop-debug) 假設此預檢已執行過;它們會從循環階段開始執行。

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

0n6k4v-Coder/skills

Translates Figma motion and animations into production-ready application code. Use when implementing animation/motion from a Figma design — user mentions "implement this motion", "add animation from Figma", "animate this component", provides a Figma URL whose node is animated, or when `get_design_context` returns motion data or instructs you to call `get_motion_context`.

0n6k4v-Coder/skills

Motion / animation context for the `use_figma` MCP tool — animating Figma nodes via manual keyframes, animation styles, easing, and timeline duration. Load alongside figma-use whenever a task involves adding, editing, or inspecting animation on a node.

0n6k4v-Coder/skills

Generate motion specification annotations from After Effects timeline data. Use when the user mentions "motion", "motion spec", "animation spec", "timeline", or wants to document a component's animation properties.

0n6k4v-Coder/skills

Turn on Cache Components in a Next.js app and resolve the blocking routes it surfaces. Use when the user wants to enable, adopt, or migrate to Cache Components, flip the `cacheComponents` flag, work through a flood of blocking-prerender / instant validation errors, run the `cache-components-instant-false` codemod, or decide between opting routes out with `export const instant = false` and fixing them in place.

0n6k4v-Coder/skills

Optimize a Next.js app that has `cacheComponents: true` — either the static shell on first paint, or the in-app navigation between routes. Picks the matching diagnostic loop and runs it.

相關技能