typescript-standards

TypeScript Standards & Best Practices

Project Tech Stack:

ALWAYS USE THE FOLLOWING IN CONJUNCTION WITH EACHOTHER TO HAVE A SAFE CODEBASE WHERE WE CAN MOVE FAST AND BREAK NOTHING

• Next.js
• Typescript + ESlint
• Zod + Prisma + tRPC + React Query
• Prisma (supabase) + Redis
• ShadCN + TailwindCSS v4
• Vitest Unit Tests

Core Principles

1. Single Source of Truth

• All types must be defined in app/types/ - Never define types inline or in component files
• Use centralized interfaces - Import from app/types/index.ts (prefered) or specific type files (only if required)
• No duplicate type definitions - If a type exists, reuse it; if it needs modification, extend it properly. Grep for the type name AND the fields of the type to help search for an existing type.
• Search before creating - Use grep to find existing types with similar fields always before creating new ones

2. Type Creation Hierarchy (in order of preference)

1. Reuse existing type from app/types/
2. Extend existing type with Pick<>, Omit<>, or interface extension
3. Compose existing types using intersection (&) or union (|)
4. ONLY as last resort - Create new interface in appropriate app/types/ file

3. Strict Type Safety

• Never use any type - Use proper typing, unknown (with documentation), or create specific interfaces if ABSOLUTELY REQUIRED
• No type assertions without validation - Use type guards instead of as casting
• Explicit return types - All functions must have explicit return type annotations
• Strict null checks - Handle null and undefined explicitly

4. unknown Type Documentation Requirement

When unknown is absolutely necessary, add a comment on the line before explaining why:

// Zod error format returns complex nested structure, casting to simplified Record for display
formattedErrors as unknown as Record<string, { _errors: string[] }>

// External API doesn't provide TypeScript types, validated at runtime
const apiResponse = data as unknown as ExternalAPIResponse;