Next.js 元件與骨架開發 (nextjs-component-dev)
專業工作流程，用於建立準備上線的 React Server Components (RSC) 和 Client Components，包含 Suspense 骨架、雙層 TDD 測試（Jest + RTL 單元測試和 Playwright 整合/渲染一致性/視覺檢查）、next-intl 字典驅動的翻譯、語意化主題代號，以及透過 next-devtools MCP 進行的即時運行診斷。
[!TIP] 模組化資產與範本：
- Next.js 文件搜尋與脈絡：
references/nextjs-docs-lookup.md- 測試架構與驗證：
references/testing-architecture-guide.md- Storybook 標準與分離：
references/storybook-reference.md- 即時導航與預先擷取：
references/instant-navigation-and-prefetching.md- Next DevTools 除錯指南：
references/next-devtools-debugging.md- 快取與重新驗證：
references/caching-and-revalidation.md- 程式碼範本：
resources/templates/（元件、骨架、Jest 單元測試、Playwright 規格）- 參考實作：
examples/- 驗證腳本：
scripts/verify-dev.ps1（Windows）/scripts/verify-dev.sh（Linux）
架構規則與標準
1. 規劃脈絡與路徑
- 讀取
docs/project.json以解析package_manager、new_component_dir、style_file_dir、component_library、dictionaries_dir（預設值："messages"）和supported_languages。 - 所有內部路由都必須使用來自
@/lib/routes的ROUTES。 - 所有作者/網站元資料都必須使用來自
@/lib/site-config的SITE_CONFIG。 - 目標路徑階層：
<new_component_dir>/<page_or_global>/<ComponentName>/- 類別：
global/用於共享佈局外框；<page-name>/（例如home/、about/、lab/）用於頁面範圍的區段。
- 類別：
2. Next.js 內部文件查詢（node_modules/next/dist/docs）
- 透過 Codebase Memory MCP 搜尋本地文件： 對於任何元件建立，都應使用
codebase-memoryMCP 工具（search_code、search_graph、get_code_snippet）主動查詢並檢查位於node_modules/next/dist/docs/的本地 Next.js 發行文件，以取得相關的 API 簽章、指令（'use cache'、'use client'、'use server'）、內建元件（next/image、next/link、next/font、<Form>）、導航鉤子（useRouter、usePathname）以及快取策略（cacheLife、cacheTag）。 - 消除已棄用項目與幻覺： 切勿依賴假設或過時的 Next.js 模式；與已安裝套件版本相符的本地
node_modules/next/dist/docs是主要的事實來源。請參閱references/nextjs-docs-lookup.md。
3. 開發伺服器與 Next DevTools 協定
- 開發伺服器檢查與接入： 在元件開發期間，透過
next-devtoolsMCP 伺服器（nextjs_index）檢查 Next.js 開發伺服器是否正在執行。 - 如果伺服器正在執行： 立即接入正在執行的伺服器和連接埠；不要重新啟動。
- 如果伺服器未執行： 在背景啟動開發伺服器（
pnpm dev、IsDaemon: true）並透過nextjs_index驗證連線。 - 運行時除錯： 實作元件後，立即查詢
next-devtools（nextjs_call）以檢查錯誤、檢查建置狀態並診斷運行時問題。請參閱references/next-devtools-debugging.md。
4. RSC 邊界與葉端 Client 下推
- 預設為伺服器元件： 保持元件為伺服器渲染（
async function）。 - 將
"use client"下推： 將互動式處理常式（按鈕、切換開關、表單輸入）隔離到小的葉端 Client Components 中。 - RSC 組合： 將 Server Components 作為
children或 props 傳入 Client 包裝器中。切勿在"use client"檔案內匯入 Server Components。
5. 樣式、邏輯屬性與主題代號
- 語意化代號： 僅使用在
app/globals.css中定義的語意化 CSS 變數（bg-background、text-foreground、border-border、text-muted-foreground）。禁止使用硬編碼的十六進位色碼（#FAFAFA）或原始顏色比例（bg-blue-500）。 - 類別合併： 始終使用
cn(...)（clsx+tailwind-merge）合併類別。 - 邏輯屬性（BiDi）： 僅使用 Tailwind 邏輯屬性（
ms-、pe-、ps-、me-、start、end）。禁止使用實體方向類別（ml-、mr-、pl-、pr-、left-、right-）。 - 進度連結： 使用來自
@vercel/react-transition-progress的<Link>作為主要導航、英雄行動呼籲和互動式卡片；對於靜態工具連結則使用標準的next/link。 - 圖片： 始終使用
next/image，並指定明確尺寸或fill、回應式sizes，以及針對上方折疊 LCP 資產使用priority。
6. 即時導航、精細 Suspense 與快取架構
- 即時元件的三個槓桿：
- 下推：將請求特定的非同步操作（
await params、await searchParams、cookies()、headers()、未快取的資料庫/API 呼叫）提取到包在<Suspense>中的葉端子元件中。靜態父層與兄弟層直接提升到靜態/應用程式殼層（App Shell）。 - 快取：在函式/元件層級將
'use cache'與cacheLife和cacheTag配對使用。使用工作階段橋接模式：- 模式 A（提取與傳遞）：從外部的
cookies()提取工作階段屬性（例如team_id、role、tier），並作為參數傳遞給'use cache'函式，使得快取資料能在所有具有匹配屬性的使用者之間共享（成本隨團隊/屬性數量擴展，而非使用者工作階段數量）。 - 模式 B（
"use cache: private"）：對於嚴格限於使用者的工作階段查詢，使用瀏覽器專用的工作階段快取，且stale >= 5m，並隨應用程式殼層一起傳遞。
- 模式 A（提取與傳遞）：從外部的
- 預先擷取策略與密集網格：
- 預設應用程式殼層預先擷取（
<Link>/prefetch={null}）：每個路由預先擷取一個共享的靜態/應用程式殼層。成本有上限（$O(\text{routes})$），每個連結零伺服器呼叫。用於密集饋送、卡片網格（50 張卡片以上）和大量導覽。 - 每連結預先擷取（
<Link prefetch={true}>）：在導覽前以每個可見連結 1 次伺服器呼叫解析動態 URL 資料（params、searchParams）。謹慎使用於高意圖的主要行動呼籲、英雄動作或主從列表項目，以消除骨架閃爍。 - 密集卡片網格：切勿在饋送中的數十張卡片上全面使用
prefetch={true}。保留預設的<Link>或使用懸停/聚焦意圖預先擷取（router.prefetch()）。
- 預設應用程式殼層預先擷取（
- 下推：將請求特定的非同步操作（
- 精細載入狀態（防止全頁閃爍）：切勿將整個元件或頁面包在單一頂層的
<Suspense>邊界中，這會導致整個骨架閃爍。讓標題、佈局框架和快取內容立即可見；僅將<Suspense>嚴格放置在動態串流插槽周圍。 - 原生 Next.js 16 快取指令：請參閱
references/instant-navigation-and-prefetching.md和references/caching-and-revalidation.md。
7. TanStack Query 與伺服器預先擷取
- 統一快取合約： 定義
key、tag和queryOptions，並加上明確的staleTime（例如30_000毫秒）。 - 伺服器預先擷取： 觸發非等待的預先擷取（
void queryClient.prefetchQuery(...)），直接呼叫內部資料庫函式（伺服器上零相對擷取）。使用<HydrationBoundary>進行解水合。 - 串流元件： 在
<Suspense fallback={<[ComponentName]Skeleton />}>內部使用useSuspenseQuery。 - 樂觀突變： 使用
useMutation，搭配onMutate快取快照和onError回滾；使用updateTag(cache.tag)呼叫伺服器動作。
8. 雙層測試分工（Jest vs. Playwright）
- Jest + RTL（
[ComponentName].test.tsx）：- 在
jsdom中快速回饋迴圈。 - Prop 排列組合、條件式 UI 元素以及空值/無效狀態。
- 透過
@testing-library/user-event進行使用者互動（絕不使用fireEvent）。 - Next.js 路由模擬（來自
next/navigation的useRouter、usePathname、useSearchParams）。 - 在
NextIntlClientProvider內部進行next-intl字典插值與複數化檢查。 - 可訪問的角色查詢（
screen.getByRole）與自動化的 a11y 檢查（jest-axe）。
- 在
- Playwright（
[ComponentName].spec.ts或頁面層級規格）：- 真實瀏覽器執行（Chromium/WebKit/Firefox）。
- 即時殼層斷言（
@next/playwright）： 使用instant(page, ...)輔助函式，在動態伺服器串流解析前，斷言靜態殼層和預先擷取的應用程式殼層會立即渲染。 - 零渲染不一致： 監聽瀏覽器控制台事件（
page.on('console')），以偵測 React SSR 水合警告，並使測試失敗。 - 視覺與 BiDi 回歸： 使用
expect(page).toHaveScreenshot()跨主題（淺色與深色 OKLCH 變數）和文字方向（dir="ltr"與dir="rtl"）進行測試。 - 網路彈性： 使用
page.route()測試慢速網路回應（驗證 Suspense 骨架幾何形狀以防止 CLS）和 500 錯誤邊界。
- 詳細測試標準： 請參閱
references/testing-architecture-guide.md。
階段 0：實作計畫與核准閘門
[!IMPORTANT] 先計畫再執行： 在執行任何寫入操作、修改字典或建立元件之前，務必先產生並呈現一個
implementation_plan.md構件，詳細說明所有計劃的檔案建立、修改、TypeScript 合約、翻譯字典新增內容以及 TDD 測試案例。等待使用者確認/核准後再繼續執行。
實作計畫必須涵蓋：
- 目標架構與路徑：完整目標目錄（
<new_component_dir>/<page_or_global>/<ComponentName>/）與分類（RSC 與 Client 葉端元件）。 - 查閱的 Next.js 本地文件：在
node_modules/next/dist/docs/下檢查的特定文件路徑（例如04-api-reference/04-components/image.md、03-directives/use-cache.md、04-api-reference/02-functions/use-router.md）。 - TypeScript 合約：Prop 介面與型別，並附帶嚴格的英文 TSDoc 註解。
- 字典策略：明確的翻譯命名空間與金鑰，需新增至
docs/project.json中所有supported_languages的messages/[locale].json檔案（零硬編碼字串或檔案內模擬字典）。 - 主題代號與樣式：識別出的語意化 OKLCH CSS 變數與邏輯佈局類別。
- 測試與診斷策略：
- Jest 單元測試（
[ComponentName].test.tsx）：模擬配置（next/navigation）、prop 變化、回呼斷言、NextIntlClientProvider整合以及 a11y 角色查詢。 - Playwright 整合情境（
[ComponentName].spec.ts）：視覺快照目標（淺色/深色主題代號、LTR 與 RTL 邏輯佈局）、網路節流/骨架幾何檢查以及水合驗證監聽器。 - Next DevTools 診斷：透過
next-devtools進行運行時錯誤與編譯檢查。
- Jest 單元測試（
- 驗證閘門：要執行的確切驗證指令（
verify-dev.ps1、目標單元測試以及 Playwright e2e 規格）。
工作流程步驟
-
步驟 0：實作計畫產生與核准閘門
- 透過
codebase-memoryMCP（search_code、search_graph）搜尋並檢查node_modules/next/dist/docs，以取得計劃元件所使用的任何 Next.js API、指令、鉤子或元件的最新脈絡。 - 綜合元件需求、掃描
docs/project.json，並產生implementation_plan.md，記錄已查閱的文件與合約。 - 在構件上設定
request_feedback = true和user_facing = true。 - 等待使用者審查並明確核准後，再撰寫任何程式碼。
- 透過
-
步驟 1：開發伺服器驗證與 Next DevTools 連線
- 透過
nextjs_index查詢next-devtoolsMCP，以偵測正在執行的 Next.js 開發伺服器實例。 - 如果開發伺服器正在執行： 接入使用中的連接埠和伺服器實例；繼續開發而不重新啟動。
- 如果開發伺服器未執行： 在背景啟動開發伺服器（
pnpm dev、IsDaemon: true），並使用nextjs_index驗證發現。
- 透過
-
步驟 2：字典填入與 TypeScript 合約定義
- 讀取
docs/project.json以解析dictionaries_dir（messages為預設值）和supported_languages。 - 定義元件的翻譯命名空間和金鑰。
- 在撰寫 JSX 之前，以真實的翻譯填入所有字典檔案（
messages/en.json、messages/fa.json等），涵蓋每種支援的語言。 - 使用嚴格的英文 TSDoc 註解（
@param、@defaultValue、@returns）定義 prop 介面。 - 如果支援的語言超過一種，元件必須先取得翻譯，如果失敗則使用備用方案。
- 讀取
-
步驟 3：TDD 基準單元測試（透過 Jest + RTL 的
[ComponentName].test.tsx）- 在實作元件之前撰寫
[ComponentName].test.tsx。 - 模擬
next/navigation鉤子（useRouter、usePathname、useSearchParams）。 - 在
NextIntlClientProvider中包裝渲染的元件，並提供字典messages和啟用的locale。 - 測試方向屬性（
dir="rtl"與dir="ltr"）、預設 props、互動式回呼（@testing-library/user-event）、Suspense 骨架備用內容以及語意化 ARIA 角色。
- 在實作元件之前撰寫
-
步驟 4：元件、骨架與 E2E 規格實作
- 建立目標元件目錄結構：
<new_component_dir>/<page_or_global>/<ComponentName>/。 - 實作元件（
[ComponentName].tsx）：- 無狀態 RSC 使用
async function直接渲染。 - 互動式葉端 Client 在頂端加入
'use client'。 - 匯入
@/lib/routes與@/lib/site-config。 - 使用來自
/app/globals.css的語意化 CSS 變數和邏輯 Tailwind 屬性。 - 使用
next-intl的useTranslations()（Client）或getTranslations()（Server）。 - 使用
cn()合併類別。使用符合語意的<nav>、<section>、<article>、<aside>標籤。
- 無狀態 RSC 使用
- 實作骨架（
[ComponentName]Skeleton.tsx）：- 比對最終元件的幾何形狀（寬度、高度、間距）。
- 使用 Tailwind 動畫類別（
animate-pulse、rounded-md、bg-muted）。 - 使用語意化 ARIA 屬性（
role="status"、aria-label="Loading [ComponentName]"）。
- 玩美規格實作。
- 在 Playwright 規格中使用
instant(page, ...)進行即時殼層斷言。
- 建立目標元件目錄結構：
-
步驟 5：Playwright E2E 規格實作（
[ComponentName].spec.ts）- 在步驟 4 之後撰寫規格。
- 測試靜態殼層立即渲染。
- 模擬慢速網路以驗證骨架幾何形狀。
- 在多個主題上進行視覺快照測試。
- 在 LTR 與 RTL 文字方向上測試邏輯間距。
- 測試錯誤與邊界情況（例如 API 500 錯誤）。
-
步驟 6：Next DevTools 診斷與驗證
- 使用
nextjs_query執行運行時檢查。 - 驗證在建置/編譯期間無錯誤。
- 驗證任何路由的渲染方式和原因。
- 使用
觸發模式
此技能由以下使用者訊息模式觸發：
/nextjs-component-devcreate componentnew componentbuild componentdevelop component- 任何結合實作 Next.js 元件與骨架支援的意圖，如上述步驟所述。
參考資料
- 請參閱
references/目錄以取得詳細指南。 - 請參閱
resources/templates/以取得程式碼範本。 - 請參閱
examples/以取得參考實作。 - 請參閱
scripts/以取得驗證腳本。