Communitygithub.com

Tipos TypeScript no Frontend

Todos os tipos TypeScript são definidos em `frontend/types/index.ts`. Os tipos correspondem à estrutura de resposta da API de backend e fornecem segurança de tipos em toda a aplicação frontend.

O que é Tipos TypeScript no Frontend?

Esta skill define um guia completo para criação de definições de tipos TypeScript no arquivo `frontend/types/index.ts`, seguindo padrões já estabelecidos. Ela cobre desde tipos básicos de usuário e tarefa até estruturas avançadas como respostas de API paginadas, tipos de autenticação, erros, e componentes de UI. As diretrizes incluem padronização de nomenclatura (PascalCase para interfaces e tipos de união, `ComponentName + Props` para props, `EntityName + FormData` para formulários), mapeamento de campos entre backend (snake_case) e frontend (camelCase para formulários), e uso de genéricos para estruturas reutilizáveis. A skill é útil para desenvolvedores que precisam manter consistência e segurança de tipos em projetos frontend React/TypeScript, especialmente em ambientes com APIs REST. Além disso, reforça requisitos constitucionais como FR-030 (interfaces TypeScript tipadas para todas as chamadas de API) e FR-037 (modo estrito TypeScript).

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Skill de Tipos TypeScript no Frontend

Propósito: Orientação para criação de definições de tipos TypeScript seguindo padrões existentes em frontend/types/index.ts.

Visão Geral

Todos os tipos TypeScript são definidos em frontend/types/index.ts. Os tipos correspondem à estrutura de resposta da API de backend e fornecem segurança de tipos em toda a aplicação frontend.

Padrões de Tipos de frontend/types/index.ts

1. Tipos de Usuário

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;
}

Padrão:

  • Use interface para tipos de objeto
  • Marque campos opcionais com ?
  • Use extends para herança de tipos
  • Use camelCase para tipos do frontend (mesmo que o backend use snake_case)

2. Tipos de Tarefa

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;
}

Padrão:

  • Use type para tipos de união (literais de string)
  • Use interface para tipos de objeto
  • Corresponda aos nomes de campos do backend (snake_case para campos da API como user_id, due_date, created_at)
  • Crie tipos separados para dados de formulário (todos opcionais, exceto campos obrigatórios)
  • Crie tipos separados para parâmetros de consulta (todos opcionais)

3. Tipos de Resposta da 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;
  };
}

Padrão:

  • Use tipos genéricos <T> para estruturas reutilizáveis
  • Forneça um parâmetro de tipo padrão (<T = unknown>)
  • Inclua um sinalizador booleano success
  • Inclua campos opcionais data, message e error
  • Crie um tipo separado para respostas paginadas com objeto meta

4. Tipos de Autenticação

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

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

Padrão:

  • Inclua booleano success
  • Inclua string token
  • Inclua objeto user (tipo User)
  • Inclua timestamp expiresAt para sessão

5. Tipos de Erro

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

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

Padrão:

  • Use interface para objetos de erro
  • Marque campos opcionais com ?
  • Use assinatura de índice [key: string] para tipos de objeto dinâmicos (FormErrors)

6. Tipos de 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;
}

Padrão:

  • Use type para tipos de união (literais de string)
  • Use interface para tipos de objeto
  • Inclua id para identificação única
  • Marque campos opcionais com ?

7. Tipos de Exportação/Importação

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

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

Padrão:

  • Use type para tipos de união (literais de string)
  • Use interface para objetos de resultado
  • Inclua contagens para rastreamento de sucesso/erro
  • Inclua array opcional de detalhes de erro

Convenções de Nomenclatura de Tipos

Interfaces

  • PascalCase: User, Task, ApiResponse
  • Nomes descritivos: TaskFormData, UserSignupData

Tipos (Tipos de União)

  • PascalCase: TaskStatus, TaskPriority, LoadingState
  • Nomes descritivos: ToastType, ExportFormat

Tipos de Props

  • ComponentName + Props: TaskItemProps, ProtectedRouteProps
  • Exemplo: interface TaskItemProps { task: Task; }

Tipos de Dados de Formulário

  • EntityName + FormData: TaskFormData, UserSignupData
  • Exemplo: interface TaskFormData { title: string; description?: string; }

Tipos de Parâmetros de Consulta

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

Correspondência com o Esquema do Backend

Mapeamento de Nomes de Campos

Backend (snake_case) → Frontend (camelCase para dados de formulário, snake_case para resposta da API)

// Resposta da API do backend (corresponde exatamente ao backend)
export interface Task {
  id: number;
  user_id: string;        // snake_case do backend
  title: string;
  due_date?: string;     // snake_case do backend
  created_at: string;    // snake_case do backend
  updated_at: string;    // snake_case do backend
}

// Dados de formulário do frontend (camelCase para uso mais fácil)
export interface TaskFormData {
  title: string;
  dueDate?: string;      // camelCase para o frontend
  tags?: string[];
}

Padrão:

  • Os tipos de resposta da API correspondem exatamente ao backend (snake_case)
  • Os tipos de dados de formulário usam camelCase para uso mais fácil no frontend
  • Converta entre formatos ao enviar/receber da API

Campos Obrigatórios vs Opcionais

// Resposta da API do backend (todos os campos do backend)
export interface Task {
  id: number;              // Obrigatório (do backend)
  user_id: string;         // Obrigatório (do backend)
  title: string;           // Obrigatório (do backend)
  description?: string;    // Opcional (do backend)
  completed: boolean;      // Obrigatório (do backend)
  priority: TaskPriority;  // Obrigatório (do backend)
  due_date?: string;       // Opcional (do backend)
  tags: string[];          // Obrigatório (do backend, pode ser array vazio)
  created_at: string;      // Obrigatório (do backend)
  updated_at: string;      // Obrigatório (do backend)
}

// Dados de formulário do frontend (apenas campos que o usuário pode editar)
export interface TaskFormData {
  title: string;           // Obrigatório (usuário deve fornecer)
  description?: string;    // Opcional
  priority?: TaskPriority; // Opcional (tem valor padrão)
  due_date?: string;       // Opcional
  tags?: string[];         // Opcional (pode ser array vazio)
}

Padrão:

  • Os tipos de resposta da API incluem todos os campos do backend
  • Os tipos de dados de formulário incluem apenas campos que o usuário pode editar
  • Marque campos opcionais com ?
  • Campos obrigatórios não têm ?

Padrões de Estrutura de Tipos

1. Use interface para Objetos

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

Quando usar: Tipos de objeto com propriedades

2. Use type para Uniões, Interseções ou Apelidos

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

Quando usar: Tipos de união, interseções ou apelidos de tipo

3. Use Tipos Genéricos para Estruturas Reutilizáveis

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

Quando usar: Estruturas reutilizáveis que funcionam com diferentes tipos

4. Marque Propriedades Opcionais com ?

export interface Task {
  title: string;        // Obrigatório
  description?: string; // Opcional
}

Quando usar: Campos que podem não existir

Exemplo Completo: Adicionando Novos Tipos

Passo 1: Definir Tipo da Entidade (corresponde ao backend)

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

Passo 2: Definir Tipo de Dados do Formulário (para entrada do usuário)

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

Passo 3: Definir Tipo de Parâmetros de Consulta (para consultas da API)

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

Passo 4: Usar no Cliente API

async getCategories(
  userId: string,
  queryParams?: CategoryQueryParams
): Promise<ApiResponse<PaginatedResponse<Category>>> {
  // Implementação
}

Requisitos Constitucionais

  • FR-030: Interfaces TypeScript tipadas para todas as chamadas de API ✅
  • FR-037: Modo estrito TypeScript ✅

Referências

  • Especificação: specs/002-frontend-todo-app/spec.md - Definições de entidade
  • Plano: specs/002-frontend-todo-app/plan.md - Contratos de API com tipos
  • Arquivo de Tipos: frontend/types/index.ts - Definições completas de tipos

Resumo de Padrões Comuns

  1. ✅ Use interface para tipos de objeto
  2. ✅ Use type para tipos de união (literais de string)
  3. ✅ Use tipos genéricos <T> para estruturas reutilizáveis
  4. ✅ Marque campos opcionais com ?
  5. ✅ Corresponda aos nomes de campos do backend (snake_case para respostas da API)
  6. ✅ Use camelCase para tipos de dados de formulário
  7. ✅ Crie tipos separados para dados de formulário e parâmetros de consulta
  8. ✅ Use nomes descritivos (EntityFormData, EntityQueryParams)
  9. ✅ Inclua todos os campos obrigatórios do backend
  10. ✅ Forneça parâmetros de tipo padrão para genéricos (<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

Habilidades Relacionadas