react-ops

name	react-ops
description	React development patterns, hooks, state management, Server Components, and performance optimization. Use for: react, hooks, useState, useEffect, jsx, tsx, next.js, nextjs, app router, server components, RSC, zustand, react query, component patterns, react testing library, error boundary, suspense, react 19.
license	MIT
allowed-tools	Read Write Bash
metadata	{"author":"claude-mods","related-skills":"typescript-ops, testing-ops, tailwind-ops, javascript-ops"}

React Operations

Comprehensive React skill covering hooks, component architecture, state management, Server Components, and performance optimization.

React 19 ecosystem facts verified as of 2026-07.

Hook Selection Decision Tree

What problem are you solving?
│
├─ Storing UI state that triggers re-renders
│  ├─ Simple value (string, number, boolean)
│  │  └─ useState
│  ├─ Complex state with multiple sub-values and logic
│  │  └─ useReducer (actions + reducer = predictable transitions)
│  └─ Derived from existing state
│     └─ Calculate inline or useMemo — not useState
│
├─ Referencing a value WITHOUT triggering re-render
│  ├─ DOM element reference
│  │  └─ useRef<HTMLElement>(null) + ref={ref}
│  └─ Mutable value (timer ID, previous value, counter)
│     └─ useRef (mutate ref.current directly)
│
├─ Running a side effect
│  ├─ After every render (or specific deps)
│  │  ├─ Needs cleanup (subscription, timer, abort)
│  │  │  └─ useEffect with return cleanup function
│  │  └─ No cleanup (logging, analytics)
│  │     └─ useEffect with empty or dep array
│  ├─ Before browser paint (DOM mutation, animation)
│  │  └─ useLayoutEffect
│  └─ Triggered by user action (not render)
│     └─ Call it directly in the event handler — not useEffect
│
├─ Caching an expensive computation
│  └─ useMemo(() => expensiveCalc(a, b), [a, b])
│
├─ Stable callback reference for child props / event handlers
│  └─ useCallback(() => doThing(dep), [dep])
│
├─ Reading shared context value
│  └─ useContext(MyContext)
│
├─ Generating stable unique ID (forms, aria)
│  └─ useId()
│
├─ Syncing external store (Redux, Zustand internals)
│  └─ useSyncExternalStore(subscribe, getSnapshot)
│
└─ React 19+
   ├─ Await a promise or read context
   │  └─ use(promise | context)
   ├─ Form submit state (pending, data, action)
   │  └─ useFormStatus / useActionState
   └─ Optimistic UI before server response
      └─ useOptimistic(state, updateFn)

Component Pattern Decision Tree

What's your composition challenge?
│
├─ Group of related components sharing implicit state
│  (Tabs, Accordion, Select, Menu)
│  └─ Compound Components with Context
│     Parent provides state via Context
│     Children consume via useContext
│
├─ Consumer needs to control rendering output
│  └─ Render Props: children(props) or render={fn}
│     Good for: headless UI, flexible layouts
│
├─ Apply cross-cutting concerns (auth, logging, theming)
│  to multiple components
│  └─ Higher-Order Components (HOC)
│     Wrap with withAuth(Component) or withLogging(Component)
│     Prefer custom hooks for pure logic
│
├─ Encapsulate reusable stateful logic
│  └─ Custom Hook — always prefer over HOC when possible
│     Composable, testable, no wrapper hell
│
├─ Need imperative control from parent (focus, scroll, reset)
│  └─ forwardRef + useImperativeHandle
│
├─ Render content outside DOM hierarchy (modal, tooltip, toast)
│  └─ Portal: createPortal(content, document.body)
│
├─ Accept arbitrary children/slots without prop drilling
│  └─ Slot pattern via children, or named props (header, footer)
│
└─ Polymorphic rendering (button that renders as <a> or div)
   └─ as prop pattern with TypeScript generics

State Management Decision Tree

Where does this state live and who owns it?
│
├─ Only one component needs it
│  └─ useState or useReducer (local state)
│
├─ A few nearby components need it
│  └─ Lift state to nearest common ancestor + prop drilling
│     (2-3 levels is fine)
│
├─ Many components need it, rarely changes
│  (theme, locale, auth user)
│  └─ React Context API
│     Split contexts by update frequency
│     Avoid single giant context
│
├─ Global client state, changes often
│  (shopping cart, UI preferences, navigation)
│  ├─ Simple/small app → Zustand (minimal boilerplate)
│  ├─ Atomic updates, React Suspense integration → Jotai
│  └─ Large team, time-travel debugging, complex logic → Redux Toolkit
│
├─ Server state (remote data, cache, sync)
│  (API data, database queries)
│  └─ TanStack Query (React Query)
│     Handles: caching, background refetch, loading/error
│     Don't use useState + useEffect for server data
│
└─ Form state
   └─ React Hook Form + Zod validation
      (controlled inputs are fine for simple forms)

React 19 Quick Reference

Feature	API	Purpose
use() hook	use(promise) / use(context)	Await promises in render, read context conditionally
Actions	async function action(formData)	Async transitions with built-in pending state
useActionState	useActionState(action, initialState)	Action result + pending state
useFormStatus	useFormStatus()	Pending/data/method inside form
useOptimistic	useOptimistic(state, updateFn)	Optimistic UI before server response
React Compiler	Automatic memoization	Replaces most memo, useMemo, useCallback
ref as prop	<Input ref={ref}>	No more forwardRef wrapper needed
<Context> as provider	<MyContext value={val}>	No more <MyContext.Provider>

// React 19: use() for data fetching in Server Components
import { use } from 'react';

function UserProfile({ userPromise }: { userPromise: Promise<User> }) {
  const user = use(userPromise); // suspends until resolved
  return <h1>{user.name}</h1>;
}

// React 19: useActionState
import { useActionState } from 'react';

function ContactForm() {
  const [state, action, isPending] = useActionState(
    async (prevState: State, formData: FormData) => {
      const result = await submitContact(formData);
      return result;
    },
    { error: null }
  );

  return (
    <form action={action}>
      <input name="email" type="email" />
      <button disabled={isPending}>
        {isPending ? 'Sending...' : 'Send'}
      
      {state.error && {state.error}}
    
  );
}

Server vs Client Components

Does this component need...?
│
├─ useState, useReducer, useContext
│  └─ Client Component ('use client')
│
├─ useEffect, useLayoutEffect
│  └─ Client Component ('use client')
│
├─ Browser APIs (window, document, localStorage)
│  └─ Client Component ('use client')
│
├─ Event handlers (onClick, onChange, onSubmit)
│  └─ Client Component ('use client')
│
├─ Third-party libraries that use hooks/browser APIs
│  └─ Client Component ('use client')
│
├─ Direct database/file system access
│  └─ Server Component (default, no directive)
│
├─ Access to env vars (server-only secrets)
│  └─ Server Component
│
├─ Large dependencies you want to keep off the client bundle
│  └─ Server Component
│
└─ async/await at the top level
   └─ Server Component

Client boundary rules:

• 'use client' marks a boundary — everything imported below it becomes client JS
• Server Components can import Client Components (they pass as props/children)
• Client Components CANNOT import Server Components directly
• Pass Server Component output as children prop to Client Components
• Server data → Client: pass as serializable props only (no functions, classes, DOM nodes)

Performance Checklist

Technique	When to Use	When NOT to Use
React.memo	Component re-renders often with same props	Nearly everything — adds comparison overhead
useMemo	Expensive calculation (>1ms), stable dep array	Primitive values, simple expressions
useCallback	Callback passed to memoized child or in dep array	Inline handlers on DOM elements
React.lazy + Suspense	Large components not needed on initial load	Small components, SSR-critical content
useTransition	Non-urgent state updates (filtering, sorting)	Time-sensitive UI (typing, hover)
useDeferredValue	Derived expensive render from fast-changing value	Same as above
Virtualization	Lists >100 items	Small lists — overhead not worth it
React Compiler (v19)	Automatic — replaces most manual memoization	Opt-out with "use no memo" if needed

Common Gotchas

Gotcha	Why It Happens	Fix
Stale closure in useEffect	Callback captures old state/prop at definition time	Add value to dep array, or use functional update setState(prev => ...)
Missing useEffect dependency	Linter disabled or ignored, stale data shown	Never disable exhaustive-deps; use useCallback to stabilize functions
Index as list key	Keys change on reorder/insert, causing wrong component identity	Use stable unique ID from data (item.id)
Hydration mismatch	Server HTML doesn't match first client render	Avoid typeof window, random values, or dates in render; use useEffect for client-only content
Unnecessary re-renders from context	All consumers re-render when any context value changes	Split context by concern; memoize context value with useMemo
useEffect for derived state	State derived from another state causes extra render cycle	Compute derived value during render inline or with useMemo
Missing cleanup in useEffect	Memory leaks from subscriptions, timers, fetch requests	Always return cleanup function; use AbortController for fetch
Strict Mode double invocation	Effects run twice in dev to catch bugs	Design effects to be idempotent; cleanup must fully reverse effect
Controlled/uncontrolled switch	value prop toggling between defined and undefined	Always provide defined value or always use defaultValue; never both
Object/array in dep array	New reference every render triggers effect repeatedly	Memoize with useMemo; use primitive values in deps where possible
Async function directly in useEffect	useEffect(() => async () => {}) returns a Promise, not cleanup	Wrap: useEffect(() => { async function run() {...}; run(); }, [])

Reference Files

File	When to Load
./references/hooks-patterns.md	Deep hook usage: custom hooks, React 19 hooks, useEffect patterns, hook composition
./references/component-architecture.md	Compound components, HOC, render props, portals, forwardRef, polymorphic components
./references/state-management.md	Context API, Zustand, Jotai, Redux Toolkit, TanStack Query, React Hook Form
./references/server-components.md	RSC architecture, Server Actions, Next.js App Router, caching, streaming, metadata
./references/performance.md	React.memo, code splitting, virtualization, React Compiler, Web Vitals, profiling
./references/testing.md	RTL queries, user-event, MSW, renderHook, Vitest setup, accessibility testing

Staleness Verifier

This skill encodes fast-moving facts (the React 19 API surface, the ecosystem package stack). scripts/check-react-facts.py guards them against silent drift — internal consistency in PR CI, live major-version drift in the scheduled freshness job:

# Structural (PR CI, no network): every catalogued package + React 19 gate is
# still named in this skill's prose, and the currency note still carries a year.
python3 skills/react-ops/scripts/check-react-facts.py --offline        # exit 0 consistent, 10 drift

# Live (weekly freshness job, never blocks a PR): is any documented major
# now behind npm's latest dist-tag?
python3 skills/react-ops/scripts/check-react-facts.py --live           # exit 10 a major moved ahead, 7 npm unreachable

The canonical fact list lives in assets/react-facts.json; when you add or drop a recommendation or the prose stops naming one, update it to match or --offline fails CI.

See Also

Skill	When to Combine
typescript-ops	TypeScript generics with React props, discriminated unions for state machines, utility types
testing-ops	Test strategy, mocking patterns, CI integration, snapshot vs behavioral tests
tailwind-ops	CSS-in-JS alternatives, responsive design with Tailwind in React components
javascript-ops	Async patterns, Promises, generators, module system fundamentals