React Best Practices Agent Skill

React Best Practices

Pair with TypeScript

When working with React, always load both this skill and typescript-best-practices together. TypeScript patterns (type-first development, discriminated unions, Zod validation) apply to React code.

Core Principle: Effects Are Escape Hatches

Effects let you "step outside" React to synchronize with external systems. Most component logic should NOT use Effects. Before writing an Effect, ask: "Is there a way to do this without an Effect?"

Decision Tree

• Need to respond to user interaction? Use event handler
• Need computed value from props/state? Calculate during render
• Need cached expensive calculation? Use useMemo
• Need to reset state on prop change? Use key prop
• Need to synchronize with external system? Use Effect with cleanup
• Need non-reactive code in Effect? Use useEffectEvent
• Need mutable value that doesn't trigger render? Use ref

When to Use Effects

Synchronizing with external systems: browser APIs (WebSocket, IntersectionObserver), third-party non-React libraries, window/document event listeners, non-React DOM elements (video, maps).

When NOT to Use Effects

• Derived state — calculate during render
• Expensive calculations — use useMemo
• Resetting state on prop change — use key prop
• Responding to user events — use event handlers
• Notifying parent of state changes — update both in the same event handler
• Chains of effects — calculate derived state and update in one event handler

Refs

• Use for values that don't affect rendering (timer IDs, DOM node references)
• Never read or write ref.current during render; only in event handlers and effects
• Use ref callbacks (not useRef in loops) for dynamic lists
• Use useImperativeHandle to limit what parent can access

Custom Hooks

• Share logic, not state — each call gets an independent state instance
• Name useXxx only if it actually calls other hooks; otherwise use a regular function
• Avoid lifecycle hooks (useMount, useEffectOnce) — use useEffect directly so the linter catches missing deps
• Keep focused on a single concrete use case

Component Patterns

• Controlled: parent owns state; uncontrolled: component owns state
• Prefer composition with children over prop drilling
• Treat boolean props that switch large component trees (isEditing, isThread, hideAttachments) as a composition smell; prefer separate composed components for distinct use cases
• For complex reusable UI, prefer compound components with provider-scoped state/actions over monolithic components with many optional props
• Use Context for scoped component families as well as truly global state, when it defines a local interface consumed by descendants
• Render JSX directly for UI variation; avoid config-array mini-frameworks unless the config is real domain data
• Lift the provider boundary when sibling or external controls need access to the same state/actions
• Use flushSync when you need to read the DOM synchronously after a state update

See react-patterns.md for code examples and detailed patterns.