React Best Practices

Check sibling files for existing patterns first — consistency beats any practice here.

Conventions

Apply to every React file:

• •Component ordering: hooks → state → derived values → event handlers → early returns → render
• •use() replaces useContext() — can be called conditionally (React 19)
• •ref is a regular prop — forwardRef deprecated (React 19)
• •useEffectEvent separates event logic from effect dependencies (React 19.2+)
• •React Compiler auto-memoizes — manual memo/useMemo/useCallback often unnecessary. Follow Rules of React strictly. Use "use no memo" to opt out
• •<Activity mode="visible|hidden"> preserves state for hidden content (tabs, navigation)
• •0 && <Component /> renders "0" — use count > 0 && or ternary
• •Immutable array methods: .toSorted(), .toReversed(), .toSpliced(), .with()
• •Functional setState: setItems(curr => [...curr, newItem]) — prevents stale closures
• •Module-level app init with let didInit = false guard — not in effects (double-fires in StrictMode)
• •Named exports over default exports — grep-able, refactoring-safe
• •Absolute imports via @/ prefix — never deep ../../../ chains
• •Lazy state initialization: useState(() => expensive()) — not useState(expensive())

References

Read the reference that matches the current task:

• •composition.md — Building components: compound components, variants, boolean props, context interfaces
• •state-management.md — Managing state or writing hooks: colocation, Context, external stores, custom hook patterns
• •effects.md — Deciding whether to use an effect: 12 anti-patterns and alternatives
• •performance.md — Optimizing performance: rendering, bundle size, waterfalls
• •data-fetching.md — Fetching data: TanStack Query/SWR, caching, mutations, optimistic updates
• •forms.md — Building forms: useActionState, useOptimistic, useFormStatus
• •server-rendering.md — Server-side React: RSC, Server Actions, serialization, SSR patterns
• •testing.md — Writing tests: RTL query priority, user-event, MSW, async patterns
• •routing.md — Setting up routes: React Router loaders/actions, lazy routes, error handling
• •styling.md — Styling: Tailwind, CSS Modules, CSS-in-JS, dark mode
• •error-handling.md — Handling errors: react-error-boundary, Suspense integration, granular boundaries
• •security.md — Security review: XSS, URL sanitization, CSP, auth tokens
• •accessibility.md — Accessibility: semantic HTML, ARIA, keyboard, focus management
• •project-structure.md — Project structure: feature-based org, colocation, naming, imports
• •typescript.md — TypeScript types: discriminated unions, generics, utility types, context typing