typescript

TypeScript & Utilities Rules

Shared Type Definitions

Core Application Types

// lib/types.ts - Always define shared types here
export interface User {
  id: string
  email: string
  name: string
  avatar?: string
  role: UserRole
  createdAt: string
  updatedAt: string
}

export interface ApiResponse<T> {
  data: T
  message: string
  success: boolean
  meta?: {
    total: number
    page: number
    limit: number
  }
}

export type UserRole = 'admin' | 'user' | 'guest'
export type Theme = 'light' | 'dark' | 'system'
export type LoadingState = 'idle' | 'loading' | 'success' | 'error'

Form Type Patterns

// Derive form types from Zod schemas
export type UserFormData = z.infer<typeof userSchema>
export type CreateUserData = z.infer<typeof createUserSchema>
export type UpdateUserData = z.infer<typeof updateUserSchema>

// Component prop types
export interface UserCardProps {
  user: User
  onEdit: (id: string) => void
  onDelete: (id: string) => void
  className?: string
}

Utility Functions

Keep Existing cn Function

// lib/utils.ts - NEVER modify this function
export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

Common Utility Patterns

// Date formatting
export function formatDate(date: Date | string, format?: string): string {
  return new Intl.DateTimeFormat('en-US', {
    year: 'numeric',
    month: 'short',
    day: 'numeric',
    ...format
  }).format(new Date(date))
}

// Debounce utility
export function debounce<T extends (...args: any[]) => any>(
  func: T,
  wait: number
): (...args: Parameters<T>) => void {
  let timeout: NodeJS.Timeout
  return (...args: Parameters<T>) => {
    clearTimeout(timeout)
    timeout = setTimeout(() => func(...args), wait)
  }
}

// Sleep utility for demos/testing
export const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))

Constants Organization

API and Route Constants

// lib/constants.ts
export const API_ENDPOINTS = {
  USERS: '/api/users',
  PRODUCTS: '/api/products',
  AUTH: '/api/auth',
} as const

export const QUERY_KEYS = {
  USERS: 'users',
  PRODUCTS: 'products',
  USER_PROFILE: 'user-profile',
} as const

export const ROUTES = {
  HOME: '/',
  DASHBOARD: '/dashboard',
  USERS: '/users',
  PROFILE: '/profile',
} as const