Frontend TypeScript Types Skill

Purpose: Guidance for creating TypeScript type definitions following existing patterns from

frontend/types/index.ts

.

Overview

All TypeScript types are defined in

frontend/types/index.ts

. Types match backend API response structure and provide type safety across the frontend application.

Type Patterns from

frontend/types/index.ts

1. User Types

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

Pattern:

• Use

  interface

  for object types
• Mark optional fields with

  ?

• Use

  extends

  for type inheritance
• Use camelCase for frontend types (even if backend uses snake_case)

2. Task Types

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

Pattern:

• Use

  type

  for union types (string literals)
• Use

  interface

  for object types
• Match backend field names (snake_case for API fields like

  user_id

  ,

  due_date

  ,

  created_at

  )
• Create separate types for form data (all optional except required fields)
• Create separate types for query parameters (all optional)

3. API Response Types

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

Pattern:

• Use generic types

  <T>

  for reusable structures
• Provide default type parameter (

  <T = unknown>

  )
• Include

  success

  boolean flag
• Include optional

  data

  ,

  message

  , and

  error

  fields
• Create separate type for paginated responses with

  meta

  object

4. Authentication Types

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

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

Pattern:

• Include

  success

  boolean
• Include

  token

  string
• Include

  user

  object (User type)
• Include

  expiresAt

  timestamp for session

5. Error Types

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

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

Pattern:

• Use

  interface

  for error objects
• Mark optional fields with

  ?

• Use index signature

  [key: string]

  for dynamic object types (FormErrors)

6. UI Types

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

Pattern:

• Use

  type

  for union types (string literals)
• Use

  interface

  for object types
• Include

  id

  for unique identification
• Mark optional fields with

  ?

7. Export/Import Types

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

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

Pattern:

• Use

  type

  for union types (string literals)
• Use

  interface

  for result objects
• Include counts for success/error tracking
• Include optional error details array

Type Naming Conventions

Interfaces

• PascalCase:

  User

  ,

  Task

  ,

  ApiResponse

• Descriptive names:

  TaskFormData

  ,

  UserSignupData

Types (Union Types)

• PascalCase:

  TaskStatus

  ,

  TaskPriority

  ,

  LoadingState

• Descriptive names:

  ToastType

  ,

  ExportFormat

Props Types

• ComponentName + Props:

  TaskItemProps

  ,

  ProtectedRouteProps

• Example:

  interface TaskItemProps { task: Task; }

Form Data Types

• EntityName + FormData:

  TaskFormData

  ,

  UserSignupData

• Example:

  interface TaskFormData { title: string; description?: string; }

Query Parameter Types

• EntityName + QueryParams:

  TaskQueryParams

• Example:

  interface TaskQueryParams { status?: "all" | "pending" | "completed"; }

Matching Backend Schema

Field Name Mapping

Backend (snake_case) → Frontend (camelCase for form data, snake_case for API response)

// Backend API response (matches backend exactly)
export interface Task {
  id: number;
  user_id: string;        // snake_case from backend
  title: string;
  due_date?: string;     // snake_case from backend
  created_at: string;    // snake_case from backend
  updated_at: string;    // snake_case from backend
}

// Frontend form data (camelCase for easier use)
export interface TaskFormData {
  title: string;
  dueDate?: string;      // camelCase for frontend
  tags?: string[];
}

Pattern:

• API response types match backend exactly (snake_case)
• Form data types use camelCase for easier frontend usage
• Convert between formats when sending/receiving from API

Required vs Optional Fields

// Backend API response (all fields from backend)
export interface Task {
  id: number;              // Required (from backend)
  user_id: string;         // Required (from backend)
  title: string;           // Required (from backend)
  description?: string;    // Optional (from backend)
  completed: boolean;      // Required (from backend)
  priority: TaskPriority;  // Required (from backend)
  due_date?: string;       // Optional (from backend)
  tags: string[];          // Required (from backend, can be empty array)
  created_at: string;      // Required (from backend)
  updated_at: string;      // Required (from backend)
}

// Frontend form data (only fields user can edit)
export interface TaskFormData {
  title: string;           // Required (user must provide)
  description?: string;    // Optional
  priority?: TaskPriority;  // Optional (has default)
  due_date?: string;       // Optional
  tags?: string[];         // Optional (can be empty array)
}

Pattern:

• API response types include all fields from backend
• Form data types only include fields user can edit
• Mark optional fields with

  ?

• Required fields don't have

  ?

Type Structure Patterns

1. Use

interface

for Objects

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

When to use: Object types with properties

2. Use

type

for Unions, Intersections, or Aliases

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

When to use: Union types, intersections, or type aliases

3. Use Generic Types for Reusable Structures

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

When to use: Reusable structures that work with different types

4. Mark Optional Properties with

?

export interface Task {
  title: string;        // Required
  description?: string; // Optional
}

When to use: Fields that may not exist

Complete Example: Adding New Types

Step 1: Define Entity Type (matches backend)

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

Step 2: Define Form Data Type (for user input)

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

Step 3: Define Query Parameters Type (for API queries)

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

Step 4: Use in API Client

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

Constitution Requirements

• FR-030: Typed TypeScript interfaces for all API calls ✅
• FR-037: TypeScript strict mode ✅

References

• Specification:

  specs/002-frontend-todo-app/spec.md

  - Entity definitions
• Plan:

  specs/002-frontend-todo-app/plan.md

  - API contracts with types
• Types File:

  frontend/types/index.ts

  - Complete type definitions

Common Patterns Summary

1. ✅ Use

   interface

   for object types
2. ✅ Use

   type

   for union types (string literals)
3. ✅ Use generic types

   <T>

   for reusable structures
4. ✅ Mark optional fields with

   ?

5. ✅ Match backend field names (snake_case for API responses)
6. ✅ Use camelCase for form data types
7. ✅ Create separate types for form data and query parameters
8. ✅ Use descriptive names (EntityFormData, EntityQueryParams)
9. ✅ Include all required fields from backend
10. ✅ Provide default type parameters for generics (

    <T = unknown>

    )