Communitygithub.com

ComeOnOliver/skillshub

所有 TypeScript 型別都定義在 `frontend/types/index.ts` 中,型別與後端 API 回應結構一致,並為前端應用程式提供型別安全。

skillshub 是什麼?

此技能提供關於在現有模式基礎上建立 TypeScript 型別定義的指南,這些模式存在於 `frontend/types/index.ts`。它涵蓋了各種型別模式,包括使用者、任務、API 回應、認證、錯誤、UI 以及匯出/匯入型別,每個模式都有清晰的範例和最佳實踐。該技能強調使用 `interface` 定義物件型別、使用 `type` 定義聯合型別、利用泛型實現可重用結構,以及遵守特定的命名慣例,例如 PascalCase 和描述性名稱,如 `EntityFormData` 或 `EntityQueryParams`。此技能支援從後端 API 回應(使用蛇形命名法)到前端表單資料(使用駝峰命名法)的映射,確保型別安全並簡化開發。它適用於如 Claude Code 和 Cursor 等平台,並參考規格文件和計劃檔案以確保實作的一致性。

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

在你喜歡的 AI 中提問

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

說明文件

前端 TypeScript 型別技能

目的:根據 frontend/types/index.ts 中的現有模式,建立 TypeScript 型別定義的指南。

概述

所有 TypeScript 型別都定義在 frontend/types/index.ts 中。型別與後端 API 回應結構一致,並為前端應用程式提供型別安全。

來自 frontend/types/index.ts 的型別模式

1. 使用者型別

export interface User {
  id: string;
  email: string;
  name: string;
  createdAt?: string;
  updatedAt?: string;
}

export interface UserCredentials {
  email: string;
  password: string;
}

export interface UserSignupData extends UserCredentials {
  name: string;
}

模式:

  • 物件型別使用 interface
  • 可選欄位標記 ?
  • 使用 extends 進行型別繼承
  • 前端型別使用駝峰命名法(即使後端使用蛇形命名法)

2. 任務型別

export type TaskStatus = "pending" | "completed";
export type TaskPriority = "low" | "medium" | "high";

export interface Task {
  id: number;
  user_id: string;
  title: string;
  description?: string;
  completed: boolean;
  priority: TaskPriority;
  due_date?: string;
  tags: string[];
  created_at: string;
  updated_at: string;
}

export interface TaskFormData {
  title: string;
  description?: string;
  priority?: TaskPriority;
  due_date?: string;
  tags?: string[];
}

export interface TaskQueryParams {
  status?: "all" | "pending" | "completed";
  sort?: "created" | "title" | "updated" | "priority" | "due_date";
  search?: string;
  page?: number;
  limit?: number;
}

模式:

  • 聯合型別(字串字面量)使用 type
  • 物件型別使用 interface
  • 匹配後端欄位名稱(API 欄位使用蛇形命名法,如 user_id、due_date、created_at)
  • 為表單資料建立獨立的型別(除了必要欄位外,其他皆為可選)
  • 為查詢參數建立獨立的型別(全部可選)

3. API 回應型別

export interface ApiResponse<T = unknown> {
  data?: T;
  success: boolean;
  message?: string;
  error?: {
    code: string;
    message: string;
    details?: unknown;
  };
}

export interface PaginatedResponse<T> {
  data: T[];
  meta: {
    total: number;
    page: number;
    limit: number;
    totalPages: number;
  };
}

模式:

  • 使用泛型 <T> 實現可重用結構
  • 提供預設型別參數(<T = unknown>)
  • 包含 success 布林標記
  • 包含可選的 data、message 和 error 欄位
  • 為帶有 meta 物件的分頁回應建立獨立的型別

4. 認證型別

export interface AuthResponse {
  success: boolean;
  token: string;
  user: User;
}

export interface Session {
  user: User;
  token: string;
  expiresAt: number;
}

模式:

  • 包含 success 布林值
  • 包含 token 字串
  • 包含 user 物件(User 型別)
  • 為 session 包含 expiresAt 時間戳記

5. 錯誤型別

export interface AppError {
  message: string;
  code?: string;
  statusCode?: number;
  field?: string;
}

export interface FormErrors {
  [key: string]: string | undefined;
}

模式:

  • 錯誤物件使用 interface
  • 可選欄位標記 ?
  • 為動態物件型別使用索引簽名 [key: string](FormErrors)

6. UI 型別

export type LoadingState = "idle" | "loading" | "success" | "error";

export type ToastType = "success" | "error" | "warning" | "info";

export interface ToastMessage {
  id: string;
  type: ToastType;
  message: string;
  duration?: number;
}

模式:

  • 聯合型別(字串字面量)使用 type
  • 物件型別使用 interface
  • 包含 id 以進行唯一標識
  • 可選欄位標記 ?

7. 匯出/匯入型別

export type ExportFormat = "csv" | "json";

export interface ImportResult {
  imported: number;
  errors: number;
  errorDetails?: string[];
}

模式:

  • 聯合型別(字串字面量)使用 type
  • 結果物件使用 interface
  • 包含成功/錯誤追蹤的計數
  • 包含可選的錯誤詳細資訊陣列

型別命名慣例

介面

  • PascalCase:User、Task、ApiResponse
  • 描述性名稱:TaskFormData、UserSignupData

型別(聯合型別)

  • PascalCase:TaskStatus、TaskPriority、LoadingState
  • 描述性名稱:ToastType、ExportFormat

Props 型別

  • ComponentName + Props:TaskItemProps、ProtectedRouteProps
  • 範例:interface TaskItemProps { task: Task; }

表單資料型別

  • EntityName + FormData:TaskFormData、UserSignupData
  • 範例:interface TaskFormData { title: string; description?: string; }

查詢參數型別

  • EntityName + QueryParams:TaskQueryParams
  • 範例:interface TaskQueryParams { status?: "all" | "pending" | "completed"; }

匹配後端結構

欄位名稱對應

後端(蛇形命名法) → 前端(表單資料使用駝峰命名法,API 回應使用蛇形命名法)

// 後端 API 回應(完全匹配後端)
export interface Task {
  id: number;
  user_id: string;        // 來自後端的蛇形命名法
  title: string;
  due_date?: string;     // 來自後端的蛇形命名法
  created_at: string;    // 來自後端的蛇形命名法
  updated_at: string;    // 來自後端的蛇形命名法
}

// 前端表單資料(為便於使用使用駝峰命名法)
export interface TaskFormData {
  title: string;
  dueDate?: string;      // 前端的駝峰命名法
  tags?: string[];
}

模式:

  • API 回應型別完全匹配後端(蛇形命名法)
  • 表單資料型別使用駝峰命名法以方便前端使用
  • 在發送/接收 API 時進行格式轉換

必要與可選欄位

// 後端 API 回應(所有來自後端的欄位)
export interface Task {
  id: number;              // 必要(來自後端)
  user_id: string;         // 必要(來自後端)
  title: string;           // 必要(來自後端)
  description?: string;    // 可選(來自後端)
  completed: boolean;      // 必要(來自後端)
  priority: TaskPriority;  // 必要(來自後端)
  due_date?: string;       // 可選(來自後端)
  tags: string[];          // 必要(來自後端,可為空陣列)
  created_at: string;      // 必要(來自後端)
  updated_at: string;      // 必要(來自後端)
}

// 前端表單資料(僅使用者可編輯的欄位)
export interface TaskFormData {
  title: string;           // 必要(使用者必須提供)
  description?: string;    // 可選
  priority?: TaskPriority;  // 可選(有預設值)
  due_date?: string;       // 可選
  tags?: string[];         // 可選(可為空陣列)
}

模式:

  • API 回應型別包含後端的所有欄位
  • 表單資料型別僅包含使用者可編輯的欄位
  • 可選欄位標記 ?
  • 必要欄位不標記 ?

型別結構模式

1. 物件使用 interface

export interface User {
  id: string;
  email: string;
}

使用時機:具有屬性的物件型別

2. 聯合、交集或別名使用 type

export type TaskStatus = "pending" | "completed";
export type TaskPriority = "low" | "medium" | "high";

使用時機:聯合型別、交集或型別別名

3. 可重用結構使用泛型

export interface ApiResponse<T = unknown> {
  data?: T;
  success: boolean;
}

使用時機:可與不同型別搭配使用的可重用結構

4. 可選屬性標記 ?

export interface Task {
  title: string;        // 必要
  description?: string; // 可選
}

使用時機:可能不存在的欄位

完整範例:新增型別

步驟 1:定義實體型別(匹配後端)

export interface Category {
  id: number;
  user_id: string;
  name: string;
  color?: string;
  created_at: string;
  updated_at: string;
}

步驟 2:定義表單資料型別(用於使用者輸入)

export interface CategoryFormData {
  name: string;
  color?: string;
}

步驟 3:定義查詢參數型別(用於 API 查詢)

export interface CategoryQueryParams {
  search?: string;
  page?: number;
  limit?: number;
}

步驟 4:在 API 客戶端中使用

async getCategories(
  userId: string,
  queryParams?: CategoryQueryParams
): Promise<ApiResponse<PaginatedResponse<Category>>> {
  // 實作
}

規範要求

  • FR-030:所有 API 呼叫的已輸入 TypeScript 介面 ✅
  • FR-037:TypeScript 嚴格模式 ✅

參考資料

  • 規格:specs/002-frontend-todo-app/spec.md - 實體定義
  • 計畫:specs/002-frontend-todo-app/plan.md - 帶有型別的 API 合約
  • 型別檔案:frontend/types/index.ts - 完整的型別定義

常見模式摘要

  1. ✅ 物件型別使用 interface
  2. ✅ 聯合型別(字串字面量)使用 type
  3. ✅ 可重用結構使用泛型 <T>
  4. ✅ 可選欄位標記 ?
  5. ✅ 匹配後端欄位名稱(API 回應使用蛇形命名法)
  6. ✅ 表單資料型別使用駝峰命名法
  7. ✅ 為表單資料和查詢參數建立獨立的型別
  8. ✅ 使用描述性名稱(EntityFormData、EntityQueryParams)
  9. ✅ 包含後端的所有必要欄位
  10. ✅ 為泛型提供預設型別參數(<T = unknown>)

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

相關技能