frontend-typescript-rules

TypeScript Development Rules (Frontend)

Frontend-specific React/TypeScript rules for implementation: thresholds, boundary type safety, component/state design, error handling, and project conventions.

Prerequisite Detection

Inspect TypeScript, bundler/framework, lint/format, path-alias, React compiler, and representative component configuration before applying a project convention. Treat a convention as observed when configuration or an established repository pattern supports it; label a conclusion from limited examples as inferred. When conflicting patterns affect public behavior, compatibility, or component boundaries, stop and name the required source or decision.

Anti-patterns and Thresholds

Signals that trigger a design change:

• Prop drilling through 3+ levels → lift to Context or state management
• Component over 300 lines → split
• Props count over 10 → split the component (3-7 is the working range)
• Optional props over 50% → introduce defaults or Context
• Props nesting deeper than 2 levels → flatten
• The same as assertion appearing 3+ times → revisit the type design

Type Safety at Boundaries

Receive untrusted or unavailable types as unknown and narrow them with a type guard. Use as only when a runtime/framework invariant proves the asserted type and record that invariant in a nearby comment. Existing generated or third-party declarations that contain any are boundary inputs to wrap, not justification for spreading any into application contracts.

Inside the app, React Props/State are type-guaranteed — no unknown needed. At every external boundary, receive as unknown and narrow with a type guard before use: API responses, localStorage/sessionStorage, URL parameters, parsed JSON. Controlled-component form input stays type-safe through React synthetic events.

const raw: unknown = await (await fetch(url)).json()
if (!isUser(raw)) throw new ValidationError('invalid user')
const user = raw // narrowed to User