React

User preferences and memory live in ~/Clawic/data/react/ (see setup.md on first use, memory-template.md for the file format). If you have data at an old location (~/react/ or ~/clawic/react/), move it to ~/Clawic/data/react/.

When To Use

• Building React components, features, or app architecture
• Choosing or wiring state (useState, Context, Zustand, TanStack Query)
• Working with React 19: Server Components, use(), Actions, React Compiler
• Debugging rerenders, infinite loops, stale closures, hydration errors, racing fetches
• Testing components, typing props, migrating legacy React code
• Reviewing AI-generated React for the failure patterns listed here
• Not for routing/deployment specifics (nextjs skill) or mobile (react-native skill)

Quick Reference

Depth on demand: debug.md symptom→cause chains · state.md server/client/URL state · server-components.md RSC boundaries and Actions · hooks.md effect discipline, refs, custom hooks · performance.md profiling and fixes in priority order · forms.md validation, wizards, uploads · testing.md Testing Library, MSW, async · typescript.md typing patterns · accessibility.md focus, ARIA, keyboard · migration.md upgrades and legacy code · setup.md scaffolding and recommended stack.

Core Rules

1. Server state ≠ client state. API data lives in TanStack Query (a cache with a lifecycle); UI state in useState/Zustand. Mixing them means hand-rebuilding dedupe, caching, and invalidation — badly.
2. No effect without an external system. Derivable from props/state → compute in render: const total = items.reduce(...). Before writing useEffect ask "what outside React am I synchronizing with?" No answer → no effect (hooks.md for the full replacement table).
3. 'use client' marks a boundary, not a component. Everything that file imports joins the client bundle. Put it on leaf interactive components; pass Server Components through as children.
4. Stable keys — and keys as a tool. key={item.id} for lists; deliberately changing a key is the sanctioned way to reset component state.
5. Named exports only. export function UserCard — rename refactors stay safe, imports stay greppable.
6. Memoize by evidence. React Compiler on: write no memo/useMemo/useCallback by hand — the compiler bails out on components that break the Rules of React, it doesn't fix them. Compiler off: memoize only after the Profiler shows the same component committing repeatedly with unchanged props.
7. strict: true plus noUncheckedIndexedAccess. With it, array[0] is T | undefined — the "impossible" runtime crash becomes a compile error.
8. Split at ~50 lines of JSX or ~300 lines per file (house default, not dogma): past that, the extraction candidates are already visible in the markup.

Error Messages Decoded

Component Rules

export function UserCard({ user, onEdit }: UserCardProps) {
  // 1. Hooks first, unconditional
  const [isOpen, setIsOpen] = useState(false)
  // 2. Derived values in render — never in an effect
  const fullName = `${user.firstName} ${user.lastName}`
  // 3. Handlers
  const handleEdit = () => onEdit(user.id)
  // 4. Early returns AFTER all hooks
  if (!user.isVisible) return null
  // 5. JSX
  return (...)
}

Export the props interface (typescript.md for variant props, generics, event types). Early returns must come after every hook call — a conditional return above a hook changes hook order between renders and crashes.

State Management

Is it from an API?
├─ YES → TanStack Query (not Redux, not Zustand, not Context)
└─ NO → Should it survive refresh / be shareable? → URL searchParams
    └─ NO → Shared across components?
        ├─ YES → Zustand (changes often) or Context (rarely changes)
        └─ NO → useState

Load-bearing defaults (full patterns, pagination, optimistic updates, persistence: state.md):

• TanStack Query >=5: staleTime defaults to 0 — every mount and window refocus refetches. Set it per resource: staleTime = how stale the user can tolerate that data. Keep gcTime (default 5 min) ≥ staleTime. Query keys come from a key factory, one source of truth.
• Zustand >=5: read with selectors — bare useStore() rerenders on every store change; selectors returning fresh objects need useShallow. One store per concern — a god-store recreates Redux without the devtools.
• Context: every value change rerenders every consumer, no selectors. Memoize the value object; split state and dispatch into two contexts so setter-only consumers never rerender.

React 19

• Server Components render on the server, ship zero JS; client components are the interactive leaves. Serialization rules, streaming, and Server Actions: server-components.md.
• use(promise) suspends until resolved and may be called conditionally — the one exception to hook rules. Never create the promise inside a client render (new promise each render suspends forever): create it in the parent or cache it.
• ref is a normal prop — forwardRef is no longer needed. `` renders as a provider directly. Migration of legacy patterns: migration.md.
• Actions: useActionState(action, initial) returns [state, formAction, pending]; useFormStatus reads pending from any child of the form — no prop drilling into submit buttons; useOptimistic renders the optimistic value and reverts automatically on throw. Worked form example: forms.md.

Performance

Order of operations — measure before touching code (workflow in performance.md):

Output Gates

Before emitting a component or review verdict, verify:

• Every list key a stable identity, never the index on reorderable data?
• Every useEffect names an external system; derivable values computed in render?
• 'use client' only on interactive leaves; no server-only import crossing the boundary?
• Mutations invalidate or update their query keys?
• Interactive elements are native (button, a, label) with accessible names?
• Error path rendered — boundary or explicit error state, not just the happy path?
• New abstraction has a second consumer, or stays concrete?

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/react/config.yaml.

Preference areas to record as the user reveals them:

• tooling — test runner (Vitest/Jest), lint/format stack, monorepo layout — affects testing.md examples and scaffold commands
• conventions — file naming, folder structure, component patterns beyond the named-export rule — affects generated file layout
• platform — SSR requirements, target browsers, deployment target — affects hydration guidance and performance budgets
• safety posture — how aggressively to flag legacy patterns and AI mistakes during review (rewrite vs comment) — affects review behavior

Per-project facts (React version, Compiler on/off, stack deviations) belong in memory.md, not config — they change per repo, not per user.

Traps

// Cancellation — the race-condition fix
useEffect(() => {
  const controller = new AbortController()
  fetch(url, { signal: controller.signal })
    .then((r) => r.json())
    .then(setData)
    .catch((e) => { if (e.name !== 'AbortError') setError(e) })
  return () => controller.abort()
}, [url])

AI Mistakes to Avoid

Patterns generated code gets wrong — check these when reviewing:

Where Experts Disagree

• Memoize-by-default vs profile-first. The React Compiler settles it for new code (write none). For pre-compiler codebases: libraries and design systems memoize exports defensively (unknown consumers); apps profile first.
• RSC-everything vs SPA. Content and commerce sites win with Server Components (payload, SEO). Dashboard-dense apps behind a login with constant interactivity lose little by staying SPA (Vite) — don't pay the RSC mental tax for zero SEO benefit.
• Zustand vs Context for shared state. Context is fine while values change rarely; the crossover is update frequency, not app size. Frequent updates through Context force consumer-tree rerenders that selectors avoid.
• Feature folders vs type folders. Type folders (components/, hooks/) survive only in small apps; beyond a handful of features, colocation by feature keeps change surface local. Default to feature folders (→ setup.md).
• Form libraries vs platform forms. A login form needs no library — useActionState + FormData is enough. The crossover is client-side validation complexity and dynamic fields, not form count (forms.md).

Related Skills

More Clawic skills, get them at https://clawic.com/skills/react (install if the user confirms):

• frontend-design-ultimate — complete UIs with React + Tailwind
• typescript — TypeScript beyond component typing: generics, tsconfig, declaration files
• nextjs — Next.js App Router, caching, and deployment
• testing — testing strategy beyond components

Feedback

• If useful, star it: https://clawic.com/skills/react
• Latest version: https://clawic.com/skills/react

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/react.