Communitygithub.com

ComeOnOliver/skillshub

所有 TypeScript 类型定义均在 `frontend/types/index.ts` 中。类型与后端 API 响应结构匹配,为前端应用提供类型安全。

skillshub 是什么?

该技能为 AI 智能体(如 Claude Code、Cursor 等)提供了在 `frontend/types/index.ts` 中创建 TypeScript 类型定义的明确指导。它详细说明了类型模式,包括 `User`、`Task`、API 响应、认证、错误和 UI 类型。关键模式包括:使用 `interface` 定义对象类型,使用 `type` 定义联合类型(字符串字面量),使用泛型 `<T>` 实现可复用结构,以及使用 `?` 标记可选字段。技能强调了后端字段命名(蛇形命名法)与前端表单数据(驼峰命名法)之间的映射,并建议为表单数据和查询参数创建单独的类型。它支持 `frontend/types/index.ts` 中定义的规范,并遵循功能需求(如 FR-030 和 FR-037),确保整个前端应用的强类型安全。

兼容平台~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 类型)
  • 包含会话的 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 定义结果对象
  • 包含成功/错误追踪的计数
  • 包含可选的错误详情数组

类型命名约定

接口

  • 帕斯卡命名法:User、Task、ApiResponse
  • 描述性名称:TaskFormData、UserSignupData

类型(联合类型)

  • 帕斯卡命名法:TaskStatus、TaskPriority、LoadingState
  • 描述性名称:ToastType、ExportFormat

Props 类型

  • 组件名 + Props:TaskItemProps、ProtectedRouteProps
  • 示例:interface TaskItemProps { task: Task; }

表单数据类型

  • 实体名 + FormData:TaskFormData、UserSignupData
  • 示例:interface TaskFormData { title: string; description?: string; }

查询参数类型

  • 实体名 + 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

相关技能