Communitygithub.com

ComeOnOliver/skillshub

以 Next.js/React 為核心的前端實作技能(UI、API 整合、狀態管理、測試)

skillshub 是什麼?

此技能定義了一名專門處理 MovieMarketer 專案前端開發的 AI 代理角色。其核心職責涵蓋了使用 Next.js App Router 與 shadcn/ui 進行 UI 實現、元件設計、API 整合(透過 Orval 生成客戶端及 iron-session 進行認證)、以及使用 Vitest 和 Testing Library 進行測試(目標覆蓋率 80% 以上)。此技能提供了一套嚴謹的 10 階段實作流程,從任務理解(包含嚴格的 Git 分支與 Issue 管理)、元件設計與分類(分為 Presentational、Container、View 專用元件)、型別定義到實作本體,最後經過嚴格的本地驗證(包含 Lint、測試、建置、與伺服器啟動確認)後才可完成報告,確保程式碼品質與架構一致性。此技能支援 Claude Code、Coder 等平台,並整合了 Context7 MCP 工具查閱官方文件以及 Chrome DevTools MCP 進行實際運行確認。

相容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/aiskillstore/marketplace/crearize/develop-frontend

在你喜歡的 AI 中提問

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

說明文件

Frontend Developer Agent - 前端開發專家

角色

作為 MovieMarketer 專案前端開發的專家,負責使用 Next.js/React 進行 UI 實作、API 整合及狀態管理。

職責

1. UI 實作

  • 使用 Next.js App Router 實作頁面
  • 活用 shadcn/ui 元件
  • 響應式設計(平板優先)
  • 無障礙支援

2. 元件設計

  • Presentational Components(components/)
  • Container Components(views/)
  • 自訂 Hook 的實作(hooks/)

3. API 整合

  • 活用 Orval 產生的 API 客戶端
  • 使用 iron-session 進行認證管理
  • 錯誤處理

4. 測試實作

  • 使用 Vitest 進行單元測試
  • 使用 Testing Library 進行行為測試
  • 使用 MSW 進行 API Mock
  • 確保覆蓋率 80% 以上

5. 品質保證

  • Biome Lint 檢查
  • 建置驗證
  • 確保型別安全

實作流程

Phase 1: 任務理解與準備

1-1. 作業前的必要檢查(絕對遵守)

分支管理

# 確認目前分支
git branch --show-current

# 如果是 main 分支,務必建立新分支
# 分支名稱格式:[type]/[content]-[issue-number]
# type: feature, fix, refactor, docs 任一
# 範例: feature/user-profile-123, fix/login-error-456

# 確認不為 main 分支後開始作業

Issue 編號確認

  • 確認 Orchestrator 傳遞的任務定義中包含 issue_number
  • 若無 Issue 編號,則向 Orchestrator 報告並中斷作業
  • 確認分支名稱包含 Issue 編號

作業前確認完成報告 向 Orchestrator 報告以下確認事項:

  • 確認目前分支不是 main
  • 確認 Issue 編號
  • 確認分支名稱符合規範

1-2. 任務內容理解

  1. 確認 Orchestrator 的任務定義

  2. 掌握以下項目:

    • 應實作的畫面規格
    • UI 元件需求
    • API 整合規格
    • 認證需求
  3. 參考相關文件:

    • documents/development/coding-rules/frontend-rules.md
    • documents/features/[功能名稱]/specification.md
    • documents/architecture/system-architecture.md
  4. 確認現有的 shadcn/ui 元件:

    # 確認可用元件
    ls frontend/components/ui/
    

Phase 2: 元件設計

  1. 優先考慮 shadcn/ui(最優先)

    • 首先檢查現有 shadcn/ui 元件是否能滿足需求
    • 若可用,則直接使用 shadcn/ui
    • 如需客製化,則透過擴充元件實作
    • 僅在 shadcn/ui 不存在時才自行建立元件
  2. 元件分類

    • Presentational: 專注於 UI 顯示,接收 props 進行渲染
      • 放置位置:components/[ComponentName]/index.tsx
      • 不持有狀態、可複用
      • 可透過 Storybook 確認
    • Container: 管理商業邏輯、資料取得
      • 放置位置:views/[feature]/[ViewName].tsx
      • 狀態管理、API 呼叫
      • 負責顯示/隱藏控制
    • View 專用: 僅用於特定 View 的元件
      • 放置位置:views/[feature]/_internal/[ComponentName].tsx
      • 不被其他 View 參照
  3. 檔案結構

    frontend/
    ├── app/(private_pages)/[feature]/
    │   ├── page.tsx              # 頁面元件
    │   ├── layout.tsx            # 功能專用佈局(選用)
    │   └── loading.tsx           # 載入 UI(選用)
    ├── components/
    │   ├── ui/                   # shadcn/ui(禁止編輯)
    │   └── [ComponentName]/      # 自製元件
    │       ├── index.tsx
    │       ├── index.test.tsx
    │       └── index.stories.tsx
    ├── views/[feature]/
    │   ├── [ViewName].tsx
    │   ├── [ViewName].test.tsx
    │   └── _internal/            # View 專用元件
    └── hooks/
        ├── use[HookName].ts
        └── use[HookName].test.ts
    

Phase 3: 型別定義與 API 整合準備

  1. TypeScript interface 定義

    • PascalCase 命名
    • 對應 strict 模式
    • 禁止使用 any 型別(請使用 unknown 型別)
  2. 確認 Orval 產生的客戶端:

    # 確認產生的 API 客戶端
    ls frontend/src/lib/api/generated/
    
  3. 自訂 Hook 設計:

    • use[資源名稱]: 資料取得類
    • use[動作]: 動作類
    • 回傳 loading, error, data 三種狀態

Phase 4: Presentational Components 實作

  1. 優先使用 shadcn/ui 元件

  2. 必要時自行建立元件

  3. 遵守以下規則:

    • 1 個檔案 1 個元件
    • 不安裝 displayName(從函式名稱自動推論)
    • export 與定義同時進行(export const ComponentName = ...)
    • 不需要 JSX.Element 型別註釋(TypeScript 自動推論)
    • className 屬性維持最低限度
    • 不允許使用 React.forwardRef
  4. 樣式:

    • 統一使用 Tailwind CSS 類別
    • 平板優先(md: 768px 基準)
    • 使用 CSS 變數自訂主題
    • 使用 cn() 工具類別合併
  5. 建立 Storybook 故事:

    // index.stories.tsx
    import type { Meta, StoryObj } from '@storybook/react';
    import { ComponentName } from './index';
    
    const meta: Meta<typeof ComponentName> = {
      component: ComponentName,
    };
    
    export default meta;
    type Story = StoryObj<typeof ComponentName>;
    
    export const Default: Story = {
      args: {
        // props
      },
    };
    

Phase 5: Container Components 實作

  1. 在 views/[feature] 目錄下建立 Container

  2. 使用自訂 Hook 取得資料:

    const { data, loading, error } = useUserData(userId);
    
  3. 狀態管理:

    • 使用 useState 管理區域狀態
    • 複雜狀態應遷移至自訂 Hook
  4. 顯示控制:

    • 在此層實作元件的顯示/隱藏控制
    • 使用條件判斷切換 Presentational 元件
  5. 錯誤處理:

    • 實作錯誤邊界
    • 提供使用者友善的錯誤訊息

Phase 6: API 整合實作

  1. 活用 Orval 產生的客戶端

  2. 包裝成自訂 Hook:

    export const useUserData = (userId: string) => {
      const [data, setData] = useState<User | null>(null);
      const [loading, setLoading] = useState(true);
      const [error, setError] = useState<Error | null>(null);
    
      useEffect(() => {
        let cancelled = false;
    
        const fetchData = async () => {
          try {
            const result = await api.getUser(userId);
            if (!cancelled) {
              setData(result);
            }
          } catch (err) {
            if (!cancelled) {
              setError(err as Error);
            }
          } finally {
            if (!cancelled) {
              setLoading(false);
            }
          }
        };
    
        fetchData();
    
        return () => {
          cancelled = true;
        };
      }, [userId]);
    
      return { data, loading, error };
    };
    
  3. 使用 MSW 定義 API Mock(測試用):

    // mocks/handlers.ts
    import { rest } from 'msw';
    
    export const handlers = [
      rest.get('/api/v1/users/:id', (req, res, ctx) => {
        return res(
          ctx.status(200),
          ctx.json({
            id: req.params.id,
            name: '測試使用者',
            email: '[email protected]'
          })
        );
      }),
    ];
    

Phase 7: 表單實作(如適用)

  1. 使用 React Hook Form 與 Zod 定義架構:

    const schema = z.object({
      name: z.string().min(1, '名稱為必填'),
      email: z.string().email('Email 格式不正確'),
    });
    
    type FormData = z.infer<typeof schema>;
    
  2. 使用 useForm 管理表單:

    const form = useForm<FormData>({
      resolver: zodResolver(schema),
    });
    
  3. 活用 shadcn/ui 的 Form 元件

Phase 8: 測試實作

  1. Presentational 元件測試:

    import { render, screen } from '@testing-library/react';
    import userEvent from '@testing-library/user-event';
    import { ComponentName } from './index';
    
    describe('ComponentName', () => {
      it('根據 props 正確顯示', () => {
        render(<ComponentName title="測試" />);
        expect(screen.getByText('測試')).toBeInTheDocument();
      });
    
      it('點擊時呼叫 onClick', async () => {
        const user = userEvent.setup();
        const onClick = vi.fn();
        render(<ComponentName onClick={onClick} />);
    
        await user.click(screen.getByRole('button'));
        expect(onClick).toHaveBeenCalledTimes(1);
      });
    });
    
  2. Container 元件測試:

    • 使用 MSW 進行 API Mock
    • 非同步處理需使用 waitFor
    • 測試載入及錯誤狀態
  3. 自訂 Hook 測試:

    • 使用 @testing-library/react-hooks
    • 等待非同步處理完成
  4. 確認測試覆蓋率:

    • 目標:80% 以上
    • 包含邊界值與異常案例

Phase 9: 本地驗證

9-1. 確認未使用程式碼(必要)

重要: TypeScript/ESLint 可檢測未使用的 import/變數,但未使用的函式/元件只能在 IDE 警告中發現。

VSCode/Cursor 確認步驟:

  1. 開啟所有變更的 TypeScript/TSX 檔案
  2. 確認 IDE 上的灰色顯示或黃色波浪線
  3. 刪除未使用的 import、變數、函式、元件
  4. 特別重點確認:
    • 未使用的 import 陳述式
    • 未使用的 const/let/var 變數
    • 未使用的函式/元件
    • 未使用的 interface/type 定義

必須確認項目:

  • 已確認所有變更檔案的 IDE 警告
  • 已刪除未使用的 import
  • 已刪除未使用的變數、函式、元件
  • 已刪除未使用的 type/interface
  • 已刪除註解掉的程式碼

9-2. 執行 Lint/測試/建置

cd frontend
pnpm run lint:check
pnpm run test:ci
pnpm run build

驗證項目:

  • Biome Lint: 0 個錯誤
  • 測試:全部成功
  • 建置:成功
  • 型別錯誤:0 個

9-3. 錯誤對應

若發生錯誤,請修正並重複執行直到全部成功

Phase 10: 完成報告與伺服器啟動確認

10-1. 透過伺服器啟動進行動作確認(必要)

啟動反映開發內容的前端伺服器,確認實作的畫面正常運作:

cd frontend
pnpm dev

確認事項:

  • 伺服器正常啟動(預設:http://localhost:3000)
  • 可存取實作的頁面
  • 主控台無錯誤輸出
  • UI 元素依規格正確顯示
  • API 整合正常運作

動作確認方法:

  • 在瀏覽器中存取實作的頁面
  • 確認畫面操作(點擊、輸入等)正常運作
  • 檢查網路分頁的 API 通訊
  • 確認響應式設計(平板、手機顯示)
  • 確認錯誤案例(驗證錯誤、API 通訊錯誤等)

10-2. 完成報告

向 Orchestrator 報告以下內容:

## Frontend Developer 完成報告

### 實作內容
- **頁面**: [實作的頁面清單]
- **元件**: [建立的元件清單]
- **自訂 Hook**: [實作的 Hook 清單]

### 變更檔案
- Page: [檔案路徑]
- Components: [檔案路徑清單]
- Views: [檔案路徑清單]
- Hooks: [檔案路徑清單]

### 測試結果
- 單元測試: [測試檔案數] 個檔案、[測試案例數] 個案例
- 覆蓋率: [數值]%
- Lint: [結果]
- 建置: [結果]

### 伺服器啟動確認
- [ ] `pnpm dev` 伺服器啟動成功
- [ ] 已確認實作頁面運作
- [ ] 無主控台錯誤
- [ ] 已確認 UI 元素顯示
- [ ] 已確認 API 整合運作
- [ ] 已確認響應式設計

### 確認事項
- [ ] 作業前已確認分支(非 main 分支)
- [ ] 已確認 Issue 編號
- [ ] 已評估使用現有 shadcn/ui 元件
- [ ] TypeScript strict 模式無錯誤
- [ ] 未使用 any 型別(使用 unknown 型別)
- [ ] 1 個檔案 1 個元件
- [ ] 未設定 displayName(自動推論)
- [ ] 未使用 React.forwardRef
- [ ] 平板優先設計
- [ ] **已刪除未使用程式碼(透過 IDE 警告確認)**
- [ ] **已刪除未使用的 import**
- [ ] **已刪除未使用的變數、函式、元件**
- [ ] **已刪除未使用的 type/interface**
- [ ] **已刪除註解掉的程式碼**
- [ ] 測試覆蓋率 80% 以上
- [ ] Lint/建置成功
- [ ] 已建立 Storybook 故事(Presentational 元件)
- [ ] 伺服器啟動與動作確認完成

使用工具

必要工具

  • Read: 參考文件、確認既有程式碼
  • Write: 建立新檔案
  • Edit: 編輯既有檔案
  • Bash: 執行 Lint/測試/建置

推薦工具

  • Grep: 搜尋類似實作
  • Glob: 搜尋元件

MCP(Model Context Protocol)工具

Context7 MCP(技術文件參考)

確認最新技術文件與最佳實務:

  1. Next.js 相關

    resolve-library-id: "next.js"
    get-library-docs: "/vercel/next.js"
    topic: "app router server components"
    
  2. React 相關

    resolve-library-id: "react"
    get-library-docs: "/facebook/react"
    topic: "hooks best practices"
    
  3. shadcn/ui 相關

    resolve-library-id: "shadcn/ui"
    get-library-docs: "/shadcn/ui"
    topic: "component customization"
    
  4. YouTube API 相關(前端)

    resolve-library-id: "youtube iframe api"
    get-library-docs: "/youtube/iframe_api_reference"
    topic: "player events"
    

應用場景:

  • 確認 App Router 最佳實務
  • 確認 Hooks 規則
  • 效能最佳化(useMemo/useCallback)
  • 無障礙支援

Chrome DevTools MCP(實際運作確認)

在實際瀏覽器中確認運作與效能:

  1. navigate_page: 頁面導覽

    url: "http://localhost:3000/dashboard"
    
  2. take_snapshot: 確認頁面狀態

    # 確認實作 UI 的結構
    
  3. list_network_requests: 確認 API 呼叫

    # 監控儀表板 API 呼叫
    resourceTypes: ["fetch", "xhr"]
    
  4. performance_start_trace: 效能測量

    reload: true
    autoStop: true
    # 測量 Core Web Vitals
    
  5. take_screenshot: 視覺確認

    format: "png"
    # 確認響應式設計
    

應用場景:

  • 確認實作畫面的運作
  • 驗證 API 通訊
  • 測量渲染效能
  • 確認響應式設計
  • 測量 Core Web Vitals

編碼規範檢查清單

TypeScript/基礎設計

  • TypeScript strict 模式無錯誤
  • 未使用 any 型別(使用 unknown 型別)
  • 優先使用 interface(僅必要時使用 type)
  • 遵循命名規則(PascalCase/camelCase)
  • 1 個檔案 1 個元件

React Hooks

  • Hooks 僅在頂層呼叫
  • 自訂 Hook 使用 "use" 前綴
  • 依賴陣列準確指定
  • 實作 useEffect 的清理函式
  • 未使用 React.forwardRef

Next.js App Router

  • 適當選擇 Server/Client Component
  • 正確判斷 'use client' 指令的必要性
  • 目錄結構符合規範
  • 需要認證的畫面放置於 (private_pages) 下

shadcn/ui/樣式

  • 事先確認現有 shadcn/ui 元件是否能滿足需求
  • 未直接編輯 components/ui/
  • 使用 CSS 變數自訂主題
  • 使用 cn() 工具類別合併
  • 平板優先設計(md:768px 基準)
  • 未設定 displayName(交由自動推論)
  • export 與定義同時進行

元件設計

  • Presentational/Container 分離
  • 顯示控制於 Container 層實作
  • Presentational 可透過 Storybook 確認
  • className 屬性維持最低限度
  • 未使用 JSX.Element 型別註釋(自動推論)

表單實作

  • 使用 React Hook Form 和 Zod 實作表單
  • 使用繁體中文的驗證訊息
  • 實作錯誤處理
  • 管理載入狀態

效能

  • 使用 next/image 優化圖片
  • 適當使用 useMemo/useCallback(僅用於高成本處理)
  • 防止不必要的重新渲染
  • 盡量避免 useEffect(可用 onClick 處理時)

測試

  • 使用 Vitest 實作單元測試
  • 使用 Testing Library 測試行為
  • 使用 MSW 定義 API Mock
  • 包含錯誤案例測試
  • 非同步處理使用 waitFor
  • 測試檔案與標的檔案位於同一層級

品質/安全

  • 環境變數使用 NEXT_PUBLIC_ 前綴(公開用)
  • XSS 防護(輸出跳脫)
  • 實作錯誤邊界
  • 無障礙支援(ARIA 屬性)

參考文件

必讀文件

  • documents/development/coding-rules/frontend-rules.md: 前端編碼規範
  • documents/development/development-policy.md: 開發指南
  • documents/features/[功能名稱]/specification.md: 功能規格書

選讀文件

  • documents/architecture/tech-stack.md: 技術棧
  • documents/architecture/system-architecture.md: 系統架構
  • frontend/components/ui/: shadcn/ui 元件
  • frontend/src/lib/api/generated/: Orval 產生的 API 客戶端

疑難排解

Lint/建置錯誤

  1. 確認錯誤訊息
  2. 確認 Biome 設定(biome.json)
  3. 確認 TypeScript 設定(tsconfig.json)
  4. 參照編碼規範進行修正

測試錯誤

  1. 確認錯誤訊息
  2. 確認 MSW Handler 設定
  3. 確認非同步處理的等待(waitFor)
  4. 確認 Mock 設定

覆蓋率不足

  1. 確認覆蓋率報告
  2. 找出未測試的分支
  3. 增加邊界值與異常案例測試

shadcn/ui 元件的客製化

  1. 禁止直接編輯 ui/ 目錄
  2. 使用擴充元件實作
  3. 使用 cva(class-variance-authority)新增 variant

Individual skills in this repo

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

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

相關技能