React Best Practices & Anti-Patterns

Modern React conventions (2025-26). Covers what to do and what to avoid. For code examples, see examples.md.

Severity Levels

Each rule is tagged with a severity for use by consuming agents:

•CRITICAL — Will cause bugs, broken reconciliation, or maintenance nightmares
•HIGH — Will cause performance issues or scaling problems
•MEDIUM — Will hurt maintainability or developer experience

Component Design (CRITICAL)

•Components must be pure — same inputs = same outputs, no side effects during render
•Business logic in hooks/helpers, NOT in component bodies
•Container components fetch data; presentational components receive props and render UI
•Helper functions extracted OUTSIDE the component body
•Max 200 lines per component — split if larger
•Max 5-7 props — more suggests the component does too much
•One component per file (small colocated internal helpers are fine)

Composition Patterns

•Compose small focused components over monolithic ones
•"Lift Content Up" — move children to the parent when the wrapper doesn't use them for logic
•"Push State Down" — keep state in the component that actually needs it
•Prefer children prop and composition over deep prop drilling

Derive, Don't Store (CRITICAL)

The #1 React anti-pattern. Look for it in every review.

•NEVER store derived values in useState — compute during render
•NEVER use useState + useEffect to sync a computed value — just compute it
•Use useMemo ONLY if the computation is expensive (measured, not assumed)
•If a value can be calculated from existing props/state, calculate it inline

State Management (HIGH)

State Location

•Colocate state with the components that use it
•Don't lift state higher than necessary — it causes unnecessary re-renders
•Don't duplicate state across components

Context API

•Context is for dependency injection (auth, theme), NOT global state management
•Context changes re-render ALL consumers — split contexts by concern
•Prefer hook return values over Context when only one subtree needs the data

State Hygiene

•Not everything needs to be in useState — only values that change over time and affect the UI
•Combine related state with useReducer instead of multiple useState calls
•URL-dependent state (filters, pagination, search) belongs in URL search params, not component state

Hooks (HIGH)

useEffect Rules

Before each useEffect, ask: Is there an external system being synchronized? If no, it's misused.

•NEVER use useEffect for derived state — compute during render
•NEVER use useEffect for event handling — put logic in the event handler
•NEVER chain useEffects that trigger each other — usually means derived state
•ALWAYS declare all dependencies correctly
•ALWAYS clean up subscriptions, timers, and event listeners

Memoization Rules

Most useMemo/useCallback calls are unnecessary. Be skeptical:

•useMemo — only for actually expensive computations (sorting large datasets, complex transforms)
•useCallback — only when the function is passed to a React.memo child
•Simple string concatenation, arithmetic, or boolean checks do NOT need memoization

Render Factories (CRITICAL)

camelCase functions returning JSX are NOT React components. They break reconciliation, hooks, and dev tools.

•NEVER use renderThing() pattern — use <Thing /> component syntax
•ALWAYS use PascalCase for anything that returns JSX
•Render factories lose component identity on every render, causing full unmount/remount

Inline Creation in JSX (HIGH)

New arrays, objects, and functions created inline in JSX props break React.memo on children.

•Extract static arrays/objects to module-level constants
•Extract dynamic arrays/objects to useMemo
•Extract inline functions to useCallback (only when passed to memoized children)

Over-Engineering (CRITICAL)

Premature Abstraction

•Abstractions with only one consumer are premature — inline it
•"Reusable" hooks with hardcoded field names are not reusable — accept config as parameters
•Context storing state that could be computed locally is over-engineered

Wrapper Components

•Components that only call a hook and return null are unnecessary — call the hook directly
•Wrappers that only pass props through add indirection without value

Data Fetching (HIGH)

•ALL data fetching in custom hooks, never in component bodies
•Use the project's useApiQuery/useApiMutation core hooks
•Handle loading, error, and empty states in the container component
•Use try-catch in async functions within hooks

Tailwind CSS (MEDIUM)

•Use utility classes for all styling — no inline style={} objects
•Use responsive prefixes (sm:, md:, lg:) for responsive design
•Extract repeated class combinations into reusable components (Button, Card, Badge)
•Prefer the project's components/ui/ over recreating common elements

Error Boundaries (HIGH)

•Use react-error-boundary package for function component-friendly API
•Include resetKeys={[location.pathname]} so boundaries reset on navigation
•Provide a "Try again" button that calls resetErrorBoundary in fallback UI
•Error boundaries do NOT catch errors in event handlers, async code, or SSR — use try/catch there

Key Prop Patterns (CRITICAL)

•NEVER use array index as key when lists can be reordered, filtered, or modified
•NEVER use Math.random() or other unstable values as keys — causes full unmount/remount
•When mapping Fragments, put key on <React.Fragment key={id}>, not on a child

Conditional Rendering (HIGH)

•NEVER use {count && <Component />} when count can be 0 — renders literal 0
•Use {count > 0 && <Component />} or ternary instead
•Replace nested ternaries with early returns or extracted components
•For multiple UI states (loading/error/empty/success), use early returns pattern

Accessibility (HIGH)

•Add aria-label to icon-only buttons — without it, they're invisible to screen readers
•Link error messages to fields with aria-describedby and aria-invalid
•Use aria-live="polite" for dynamic content updates (search results, notifications, toasts)
•Trap focus inside modals; provide escape path (Escape key + visible Close button)
•Announce route changes for screen readers (SPA navigation is silent by default)

Performance Beyond Memoization (MEDIUM)

•Use React.lazy() + <Suspense> for route-level code splitting
•Use Vite manualChunks to split vendor bundles for better caching
•Use top-level static paths in lazy(() => import('./X')) — dynamic paths break build analysis

Axios + React Patterns (HIGH)

•Cancel in-flight requests in useEffect cleanup using AbortController
•Use centralized Axios instance with baseURL, default headers, and interceptors
•Use request interceptors for auth tokens, response interceptors for 401/403 handling

React 19 Patterns (MEDIUM)

•Accept ref as a regular prop instead of using forwardRef (React 19+)
•With React Compiler enabled, avoid adding memo/useMemo/useCallback unless measured

react-best-practices