react

name	react
description	This skill should be used when the user works with React components (.tsx/.jsx), asks about "hooks", "state management", "context providers", "memo optimization", "useEffect", or discusses component composition and rendering performance. Provides patterns for hooks, state, effects, memoization, and React-specific architecture.
user-invocable	false
allowed-tools	Read, Grep, Glob
activation	{"file-patterns":["**/*.tsx","**/*.jsx"],"exclude":["node_modules/**","**/*.test.*","**/*.spec.*"]}

React Patterns

Reference for React-specific patterns with citations. Sources in references/sources.md.

Iron Law

COMPOSITION OVER PROPS [2][4][12]

Use children and compound components, not prop drilling. If a component has >5 props, it's doing too much. Split it. If you're passing data through 3+ levels, use context or composition. Props are for configuration, not data plumbing. "Before You memo(), try solving it with composition." — Dan Abramov [4]

When This Skill Activates

• Working with React codebases (.tsx, .jsx) — components, hooks, contexts, performance

---

Component Structure [1][2]

Functional component order: hooks → derived state → handlers → return. [1]

Compound components share structure through children, not props: [2][4]

function Card({ children }: { children: React.ReactNode }) {
  return <div className="card">{children}</div>;
}
Card.Header = ({ children }: { children: React.ReactNode }) =>
  <div className="card-header">{children}</div>;

Context for shared state across distant components — eliminates prop drilling: [1][2]

const AuthContext = createContext<AuthContextValue | null>(null);
export function useAuth() {
  const ctx = useContext(AuthContext);
  if (!ctx) throw new Error('useAuth must be used within AuthProvider');
  return ctx;
}

---

Hooks [3][16][24]

Hooks must be called at the top level — never inside conditions, loops, or nested functions. [16][24] Effects synchronize with external systems; they are not lifecycle methods. [3] Every effect that subscribes must return a cleanup function. Deps must be complete — never omit to suppress warnings. [3]

See references/hooks.md for rules of hooks, custom hooks, useReducer, and effect anti-patterns.

---

Performance [3][4][5][17]

The React Compiler (2024) handles many memoizations automatically [17]. For manual optimization, follow this priority: [4]

1. Composition first — "before you memo(), try passing children down" [4]
2. Extract primitives for useEffect deps — avoid object/array literals [3]
3. useMemo for expensive computations; useCallback for stable handlers [3]
4. React.memo only when parent has stable, memoized callbacks [4]
5. Virtualize long lists (react-window) [5]; lazy-load heavy components [5]

const [user, orders] = await Promise.all([fetchUser(id), fetchOrders(id)]); // parallel [1]
const filtered = useMemo(() => users.filter(u => u.name.includes(q)), [users, q]); // derived [13]
const selectedSet = useMemo(() => new Set(selected), [selected]); // O(1) lookup [5]

---

State Architecture [1][14]

Pattern	When to Use	Source
useState	Simple, independent values	[1]
useReducer	Complex state with multiple transitions	[14]
Context	Shared state across distant components	[1][2]
Server Components	Server-only data; zero bundle impact	[6][7]

Server Components render on the server and stream to the client — no useEffect or API route required for data fetching. [6][7]

---

Key Anti-Patterns [3][13]

Anti-Pattern	Correct Approach	Source
Derived state in useState + useEffect	Compute with useMemo during render	[13]
Object/array literal in useEffect deps	Extract to primitives	[3]
Missing cleanup in useEffect	Always return cleanup function	[3]
Prop drilling (3+ levels)	Context or composition	[2][4]
Barrel imports	Direct named imports (tree-shakable)	[5]
Array.find/includes in render loops	Map/Set via useMemo	[5]
Index as list key	Use stable unique IDs	[1]

---

Extended References

• references/sources.md — Full bibliography (24 sources)
• references/patterns.md — Extended correct patterns with citations
• references/violations.md — Extended violation examples with citations
• references/hooks.md — Hook rules, custom hooks, useEffect deep-dive, utilities
• references/forms.md — Controlled/uncontrolled, validation, Server Actions
• references/error-handling.md — Error boundaries, Suspense, async error states

---

Checklist

• Hooks at top level — no conditions or loops [16][24]
• All useEffect deps included; cleanup returned [3]
• useCallback for handlers to memoized children; useMemo for expensive values [4]
• Context at appropriate level — no prop drilling [2]
• Error boundaries around risky components [1]
• Unique stable keys on list items — not index [1]
• Loading and error states handled [13]
• Accessibility: aria-*, role, labels on form inputs [21][22]
• Independent fetches parallelized with Promise.all [1]
• Direct imports — no barrel imports; lazy-load heavy components [5]
• Set/Map for O(1) lookups instead of Array.includes/find [5]
• Images have explicit dimensions, lazy loading, and aspect-ratio [23]