Way TypeScript & React Style

Way Specific Conventions

• Define reusable data/logic helpers as top-level pure functions (outside React components); keep component bodies focused on rendering and wiring
• Complex predicates for array methods must be separate named functions
• Prefer declarative over imperative — derive values during render rather than storing them in let/useState; use map/filter/reduce expressions rather than loops that push into an array; use object/array spread to produce new values rather than mutating existing ones
• Always use early returns — if (isLoading) return <Spinner />; at the top, not let content with if/else branches
• Never use IIFEs — extract a named function instead: a top-level pure function for derived values, or a named inner function for JSX that closes over component state
• Avoid as casts; prefer narrowing, generics, or splitting code paths. Use as only when interoperating with external/untyped APIs and add a short justification comment
• Handle undefined args explicitly (no ?? 0 for mandatory params)
• Naming: names describe the entity, not the mechanism. No suffixes like Base/New/Old/Initial unless they carry real semantic meaning. Keep sibling verbs consistent across a related API. Avoid cryptic identifiers (v, n) for domain values — short names are fine only in conventional contexts (i, x/y, generic T/K/V)
• Code structure: prioritize reusing lib/hooks/components over duplicating logic; promote generic helpers out of feature folders into lib/ or hooks/. Keep functions small and single-purpose — split 100+ line functions into focused named helpers. Extract distinct complex JSX into named components when it helps reuse, coupling, or readability
• Comments: none by default — well-named identifiers carry the what. Add a short comment only when the why is non-obvious (a workaround, a hidden invariant, a subtle ordering constraint); never document the implementation itself
• Do NOT use useMemo or useCallback — React Compiler handles memoization. (Project AGENTS.md may define narrow exceptions.)
• STOP before writing useEffect — most uses are wrong. Evaluate the decision tree in this skill first. Effects are only for synchronizing with external systems.
• Data fetching hierarchy: Always use @connectrpc/connect-query hooks with generated *_connectquery.ts files. Only fall back to raw @tanstack/react-query when no generated file exists or the pattern cannot be expressed via connect-query.
• Hydration: Never render server-side content that depends on client state (timestamps, window checks)