typescript

TypeScript

Patterns and conventions for all TypeScript code.

Types

• import type {} for type-only imports: import type {ReactNode} from 'react'

Naming, camelCase

All identifiers use camelCase: Zod fields, form name/id/htmlFor, props, state, params.

Exceptions (snake_case OK):

• types/database.ts, mirrors DB column names
• Dynamic template literal names where variable part is already lowercase
• Environment variable names (SUPABASE_URL)

Map snake_case ↔ camelCase at API call boundaries, not in schemas or UI code.

Naming, Descriptive and Self-Documenting

Owned by the naming-conventions skill (.claude/skills/naming-conventions/SKILL.md).

Exported Functions, Explicit Return Types

All exported functions must have explicit return types.

Exceptions:

• Route loaders/actions (complex generics)
• React components (props typed inline on the destructured parameter, return type inferred)

// BAD
export const formatDate = (date: Date) => format(date, 'yyyy-MM-dd');

// GOOD
export const formatDate = (date: Date): string => format(date, 'yyyy-MM-dd');

General Rules

• Use type not interface, interfaces support declaration merging, which creates unpredictable behavior; type is consistent and predictable
• Arrays: string[] not Array<string>
• Boolean naming: ^((can|has|hide|is|show)[A-Z]|checked|disabled|required)

Code Patterns

• No switch statements, use if/else chains or object maps; switch requires break, is prone to fallthrough bugs, and is harder to type-check exhaustively
• No TypeScript enums, use as const objects with derived types; enums compile to runtime objects with surprising behavior and don't tree-shake well
• JSX boolean props: always explicit ={true}, makes props grep-able and avoids confusion when a prop is later refactored to a non-boolean type
• Max 3 function parameters, use an options object beyond that; call sites with 4+ positional args are hard to read and argument order mistakes are common
• Inline boolean coercion uses !!x, never Boolean(x); reserve Boolean for point-free use (e.g. array.filter(Boolean)), and coerce per operand in a nullable || chain (!!a || !!b), since !!(a || b) trips @typescript-eslint/prefer-nullish-coalescing
• Prefer undefined over null for GAIA-controlled absence (state, optional fields, internal sentinels); reserve null for external contracts that require it: DOM useRef(null), ref-callback params, React Router data(null), Zod .nullable(), and platform/library APIs that return null