react-patterns

name	react-patterns
description	Guides correct React implementation and component design. Use this when implementing React components, hooks, or features — read the relevant React 18 docs first, then apply the checklist before writing code. Also use this when the same pattern appears in multiple places and needs to be extracted into a shared utility or component.

React Patterns

Mandatory: Read the docs before implementing

Before writing any React feature, open and read the relevant page from the official React 18 docs at https://18.react.dev/learn. This is non-negotiable. The docs are the single source of truth for correct React patterns.

Quick-reference map — match your task to the doc:

Task	Doc to read first
Building a new component	Your First Component
Passing data between components	Passing Props to a Component
Rendering a list	Rendering Lists
Adding local state	State: A Component's Memory
Handling user events	Responding to Events
Sharing state across siblings	Sharing State Between Components
Choosing state structure	Choosing the State Structure
Complex multi-field state	Extracting State Logic into a Reducer
Avoiding prop drilling	Passing Data Deeply with Context
Deciding whether to use an effect	You Might Not Need an Effect
Writing a useEffect	Synchronizing with Effects
Accessing the DOM	Manipulating the DOM with Refs
Extracting repeated logic	Reusing Logic with Custom Hooks
Keeping components predictable	Keeping Components Pure

---

Implementation checklist

Work through this before and during writing any React code.

1. Component design

• Component is a pure function — same props always produce the same output
• No side effects during render (no fetch, no mutations, no subscriptions)
• Component has a single, clear responsibility
• Props are typed explicitly; no implicit any
• Named export used (export function Foo), not default — unless it is a Next.js page/layout

2. State

• State is placed at the lowest component that needs it
• If two components need the same state, it is lifted to their closest common parent
• State is never mutated directly — always call the setter
• Objects and arrays in state are replaced, never mutated in place:
  • Objects: setState({ ...prev, field: value })
  • Arrays: setState(prev => [...prev, newItem]) / prev.filter(...) / prev.map(...)
• State structure avoids redundancy — derived values are computed from existing state, not stored separately
• When state has 3+ sub-values that change together, useReducer is used instead of multiple useState calls

3. Effects

• Ask: "could this logic live in an event handler instead?" If yes, move it there.
• Ask: "can this be derived from existing state/props during render?" If yes, compute it — don't store it in state and sync with an effect.
• useEffect is only used for synchronizing with external systems (DOM APIs, timers, subscriptions, third-party libs)
• Every effect has a correct dependency array — no missing deps, no suppressed lint warnings
• Effects that set up subscriptions or timers return a cleanup function
• Data fetching in effects is avoided in favor of TanStack Query (project standard)

4. Lists and keys

• Every list item has a key prop
• Keys are stable and unique among siblings — always DB id, never array index for dynamic lists
• Keys are not derived from Math.random() or Date.now()

5. Refs

• useRef is only used for DOM access or storing mutable values that must not trigger re-renders
• Refs are not read or written during render
• If a value change should cause a re-render, it is state — not a ref

6. Context

• Context is only introduced when prop drilling exceeds 2–3 levels
• Context is always paired with a custom hook (useMyContext) — never consumed with bare useContext in component files
• Context value is memoized or stable to prevent unnecessary re-renders of all consumers

7. Custom hooks

• Hook name starts with use
• Hook encapsulates a single coherent piece of stateful logic
• Hook does not return JSX — it returns data and/or callbacks
• Hook dependencies are documented if non-obvious

---

When to extract shared utilities or components

Apply the rule of two: if the same pattern appears in 2 or more places, extract it before writing it a third time. Do not over-abstract on first use — write it inline, extract on second occurrence.

Decision table

What is repeating	Extract to
UI component used across 2+ dashboard pages	packages/ui/src/ (web-only; requires Tailwind)
TanStack Query hook with same shape	hooks/ directory inside the app
Pure calculation or data transformation	packages/lib/src/ — must be pure, no I/O, no side effects
Zod schema reused across 2+ forms	packages/types/src/models.ts
Mobile UI component used in 2+ screens	apps/mobile/components/
Context + hook pair used in 2+ places	Dedicated contexts/ or providers/ directory in the app

Extraction checklist

Before extracting, confirm:

• The pattern has appeared in at least 2 places (rule of two)
• The abstraction has a clear, single responsibility
• The extracted unit is independently testable
• For packages/lib: zero I/O, zero Supabase calls, zero side effects
• For packages/ui: web-only, no React Native imports
• Barrel export in src/index.ts is updated so consumers import from the package, not deep paths

---

Common anti-patterns to reject

Anti-pattern	Correct approach
useEffect to sync derived state	Compute the derived value during render
useEffect to respond to a user event	Move logic into the event handler
Array index as list key	Use stable DB id
Mutating state directly (state.x = y)	Replace with setter: setState({ ...state, x: y })
Reading a ref during render	Use state instead if the value affects output
Prop drilling 3+ levels	Lift to context with a custom hook
Same hook logic copy-pasted in 2+ files	Extract to a custom useX hook
Same UI pattern copy-pasted in 2+ files	Extract to a shared component
any type on props or state	Use explicit types; narrow with type guards
getSession() in Supabase calls	Always use getUser()