TypeScript Development Rules (Frontend)

Comment Writing Rules

Code first: names and types carry meaning; a comment must add what code cannot, and one comment per decision is enough.

• Explain why a component memoizes, guards, or re-renders, not what the JSX renders.
• Record decisions and rationale; leave chronological history to version control.

Type Safety

Default Rule: Prefer unknown, generics, or union types over any. Retain any only when an existing external, generated, or legacy public signature requires it, or when replacing it prevents the project type check from expressing a safe generic relationship. Record the declaration path or type-check result that proves the constraint. When a local adapter can preserve compatibility and expose a safer type within the user request or current task/design artifact, implement the adapter; otherwise confine any to the smallest adapter or public-signature boundary, document the reason, and validate untrusted data before it enters typed application code.

Frontend Boundaries

• React Props/State: use the declared application types.
• External API responses: treat unvalidated payloads as unknown and validate at the boundary. A generated client may retain its declared type when it also enforces the contract at runtime.
• localStorage / sessionStorage: handle string | null; treat parsed data as unknown until validated.
• URL parameters: handle the router or platform's nullable string shape, then parse and validate before converting to a domain type.
• Exported APIs and important boundaries: declare return types; allow inference for local implementations when the contract remains clear.

Type Complexity Review Signals

Use these as review prompts, not pass/fail thresholds. Existing project conventions and the component's responsibility take precedence.