typescript

name	typescript
description	Patterns and conventions for all TypeScript code. Use this skill whenever writing or reviewing TypeScript, naming identifiers, typing exports, choosing between type and interface, using Zod schemas, structuring function parameters, or enforcing code patterns like avoiding switch statements and enums.
model	haiku

TypeScript

Patterns and conventions for all TypeScript code.

Types

• import type {} for type-only imports: import type {FC} 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

Follow Apple's Swift API Design Guidelines: names should be clear at the point of use, reading like prose. Favor long, descriptive names over short or abbreviated ones. Code should be readable without consulting documentation.

• Functions and methods: imperative verb phrases: calculateProgressPercentageFromCompletedSets, processUserOnboardingProfile
• Parameters: role, not type: totalSeconds not n, emailAddress not s
• Variables: what they hold: restDurationInSeconds, submitButton, weightInputValue
• No abbreviations: spell out unless universally known (url, id, api): animationDurationInMilliseconds not animDur
• No redundant words: availableExercises not exerciseArray, but don't sacrifice clarity for brevity

Exception, React event handlers follow handle{Action}{Element} from the react-code skill (e.g. handleClickSave, handleChangeInput), the {Element} is required, since a bare handleClick or handleChange trips react-doctor/no-generic-handler-names. The descriptive naming guidelines above apply to utilities, hooks, callbacks, and non-event-handler functions.

Read references/naming-conventions.md for extended BAD/GOOD examples of each naming pattern.

Exported Functions, Explicit Return Types

All exported functions must have explicit return types.

Exceptions:

• Route loaders/actions (complex generics)
• React components typed with FC<Props> (return type provided by generic)

// 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

Zod

This project uses Zod 4, in every schema. The deprecated Zod 3 chained forms (.strict(), .email(), single-arg z.record(), .args().returns()) still type-check and lint clean, so nothing flags them, reach for the Zod 4 form deliberately.

• z.literal([...]) not z.enum() for string unions, sort values alphanumerically

Read references/zod.md for the full Zod 3 → Zod 4 migration map (z.strictObject, top-level string formats, z.record arity, function and error shapes). It opens with a standing directive to verify uncertain or suspect Zod forms against the official docs (WebFetched, auto-discovered from node_modules/zod/package.json) rather than trusting v3-era memory.