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

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

Component and State Design

• Function components only. Class components are allowed solely for Error Boundaries (no hook equivalent exists)
• Type Props explicitly with a named type and destructure: function UserCard({ user, onSelect }: UserCardProps). Type props directly on the function so the props contract stays explicit
• Props-driven: pass dependencies as props when one explicit parent owns them. Use Context or established global state when multiple non-adjacent descendants share the value and prop forwarding would add intermediate components with no ownership role
• Custom hooks are the unit of logic reuse and dependency injection (inject collaborators through the hook for testability)
• Function parameters: 0-2 positional; for 3+ take a single options object
• State shape: type state explicitly; for multi-field state with discrete transitions, use useReducer with a discriminated-union action type rather than many useState calls
• Server/Client boundary (RSC frameworks only — e.g. Next.js App Router): default to server components for data fetching/rendering and isolate interactivity behind a "use client" boundary at the smallest scope that needs it; keep browser-only APIs (window, localStorage, event handlers) inside client components, since calling them in a server component breaks the render. N/A for client-only SPAs (e.g. Vite) — skip when the project has no server-component runtime