React Patterns

React Patterns 規範

Next.js App Router 慣例

• 使用 App Router（app/ 目錄）
• 預設使用 Server Components
• 需要互動時才加 'use client'
• 路由檔案：page.tsx, layout.tsx, loading.tsx, error.tsx
• API Routes：app/api/*/route.ts

元件結構

• 一個檔案一個元件（除非是緊密耦合的小元件）
• Props 使用 TypeScript interface，命名為 {ComponentName}Props
• 預設使用 named export（非 default export）
• 元件檔案結構順序：
  1. imports
  2. types/interfaces
  3. 常數
  4. 元件函數
  5. export

狀態管理

• 簡單狀態：useState
• 複雜狀態：useReducer
• 跨元件共享：React Context（小規模）或 Zustand（中大規模）
• 伺服器狀態：搭配 Server Components + Server Actions

樣式

• 使用 Tailwind CSS utility classes
• 複雜樣式邏輯使用 clsx 或 cn() 組合
• 避免 inline style objects
• 響應式設計使用 Tailwind breakpoints（sm:, md:, lg:）

常見模式

• 表單：controlled components + server actions
• 列表渲染：確保有穩定的 key
• 條件渲染：使用 && 或三元運算子，避免 if 在 JSX 中
• 錯誤邊界：使用 error.tsx 檔案

效能

• 圖片使用 next/image
• 連結使用 next/link
• 大型列表考慮虛擬化
• 避免不必要的 re-render（適當使用 memo, useMemo, useCallback）

已知注意事項

（由 QA 迭代時追加）

詳細模式參考：references/patterns.md 歷史教訓：references/lessons.md