react-best-practices

Eliminate Waterfalls:

• Use Promise.all() for independent async operations (async-parallel)

Reduce Bundle Size:

• Avoid barrel file imports, import directly from source (bundle-barrel-imports)
• Defer non-critical third-party libraries (bundle-defer-third-party)

Client-Side Data Fetching:

• Use Tanstack Query for automatic request deduplication (client-request-dedupe)
• Dependent query params are the value or undefined, never | null or a fake fallback; narrow at the caller so hooks stay strict, or guard with skipToken when the hook must accept an optional param (client-request-dedupe)

Re-render Optimization:

• Use lazy state initialization for expensive values (rerender-lazy-state-init)
• Apply startTransition for non-urgent updates (rerender-transitions)
• Keep UI handlers plain; use Effect Events only for effect-fired logic (rerender-useeffect-function-calls)
• Never reset state with useEffect; lift the discriminant and remount the branch (rerender-no-useeffect-state-reset)
• Never add useMemo or useCallback; leave memoization decisions to developers with profiler evidence (rerender-no-usememo-usecallback)
• Never call setState during render or inside useEffect; derive during render or move state ownership to an intermediate component (rerender-no-setstate-in-render-or-effect)

Component Structure:

• One domain component/hook per file, one responsibility each — split bloated components (structure-single-responsibility)
• Keep component, hook, function, and utility APIs narrow: split oversized props, arguments, and return objects into focused units composed at the component level; wrapping the same values in one object is not a fix (structure-narrow-apis)
• Use PascalCase components for JSX-returning helpers; keep lowercase helpers for non-JSX values (structure-component-naming)
• Derive props/params instead of accepting a value computable from another arg (structure-derive-dont-duplicate)
• Extract complex derived logic into named locals plus predicates or pure helpers with early returns: oversized conditions, nested ternaries, ternaries that compute instead of picking (multi-line branches, or an as cast re-asserting what the condition tested), fallback chains, and let-based render prep are code smells, in render prep and in hook options, request builders, config maps, and reducers alike (structure-complex-derived-logic)
• Pick the view with early if guards but keep the layout wrapper in one place — branch a body component, don't ternary or duplicate the shell (structure-early-return-render-branches)
• For a fixed set of items, write one component per item with explicit props that owns its data and loading — don't map a config-object array onto a component shape (structure-composition-over-config)

Testing:

• BDD tests that drive the real @mastra/client-js + React Query stack and mock only the network; never vi.mock our own hooks/services/auth gating or the SDK (testing-bdd-no-mocks)
• Avoid class-name assertions for visual behavior; prefer computed styles, user-visible behavior, or browser validation, and prefer no test over a className-only implementation mirror (testing-no-classname-assertions)

Type Safety:

• No as type assertions anywhere — production or tests; narrow with real type guards, query generics (querySelector<T>, getByRole<T>), typed fixture factories, or implements on mocks. as const is the only allowed form. Do not replace a cast with a domain-type predicate that only checks typeof value === 'object'; call that an isRecord helper or validate the fields used (types-no-type-assertions)
• Use undefined and optional ? for absence, not null; convert external null at boundaries, and keep leaf props strict so callers own absence and fallback rendering (types-no-null)

• Animate SVG wrappers, not SVG elements directly (rendering-animate-svg-wrapper)
• Use content-visibility: auto for long lists (rendering-content-visibility)

• Use Set/Map for repeated lookups (js-set-map-lookups)
• Use toSorted() instead of sort() for immutability (js-tosorted-immutable)
• Early length check for array comparisons (js-length-check-first)