TypeScript Conventions

Project-wide TypeScript standards that complement agent-specific instructions.

Type Safety

• No any: Use unknown if the type is truly dynamic, then narrow.
• Strict config: strict: true, noUncheckedIndexedAccess, verbatimModuleSyntax.
• Use Readonly<T>, Pick, Omit, and Record for precise types.
• Use branded types for entity IDs (e.g., UserId, OrderId) to prevent mixing.
• Prefer z.infer<typeof schema> over hand-written types when a Zod schema exists.

Interface vs Type

• Interfaces for object shapes that may grow — they support extends and declaration merging.
• Type aliases for unions, intersections, mapped types, and complex compositions.
• Simple rule: interface for plain objects, type for everything else.