typescript

TypeScript Conventions

Coding conventions and best practices for TypeScript projects. Project-specific conventions (CLAUDE.md, style guides) always take priority over this guidance.

Type Definitions

• Use type over interface for object shapes, API responses, props, and general type aliases
• interface is acceptable only when declaration merging or extends is specifically needed
• Use discriminated unions with a kind or similar literal field for variant types
• String literal unions over enums: type Status = "INIT" | "READY" | "ERROR"
• Use Pick, Omit, and mapped types to derive types rather than duplicating fields
• Mark optional fields with ? — avoid | undefined unless semantically distinct

type Config = {
  region: string;
  tracks: TrackSlug[];
};

type ApiResponse =
  | { kind: "success"; data: Item }
  | { kind: "error"; message: string };

Type Safety

• Enable strict mode ("strict": true in tsconfig)
• Write type guard functions for runtime narrowing: function isScreenMode(v: string): v is ScreenMode
• Avoid any — use unknown when the type is truly uncertain, then narrow
• Use import type { ... } for type-only imports

Naming Conventions

• Files: PascalCase for components (TrackPage.tsx), camelCase for utilities and libraries (api.ts, models.ts)
• Types: PascalCase (ChatMessage, ScreenControl)
• Variables/Functions: camelCase (trackSlug, onSubmit)
• Constants: UPPER_SNAKE_CASE (HISTORY_LENGTH, ALL_TRACKS)
• Booleans: Prefix with is or should (isRequesting, shouldShowTopic)

React Components

• Functional components only — no class components
• Use ReactNode for children type
• Prefer named exports; use default exports for route-level pages or lazy-loaded components

Hooks

• useState for local state, React Context for shared/global state
• SWR (useSWR, useSWRInfinite) for server data fetching — no Redux/Zustand
• react-hook-form (useForm) for form state management
• Extract reusable logic into custom hooks (use* prefix)
• Always specify dependency arrays correctly in useEffect, useMemo, useCallback