React

React + Vite SPA — Components, State, Data Fetching (React 19.2, 2026)

Hand-off — picking dependencies. Which library to reach for (UI primitives, command menus, toasts, OTP inputs, charts, virtualization, drag and drop, state, styling, theming) is ../ui-engineering/SKILL.md's — build vs adopt is decided there, before hand-rolling a component. Animating what you install is ../motion-craft/SKILL.md's.

Build or review a fast, typed, correctly-architected client-side React single-page app bundled by Vite. No server runtime, no RSC tree, no framework router. Server-rendered React (App Router, server actions, SSR/SSG) is not this skill — that is ../nextjs/SKILL.md.

SDD gate — before writing feature code. If this skill fired on a new, non-trivial feature or behaviour change and there is no approved spec + plan under 02-DOCS/wiki/sdd/, stop and hand off to ../specify/SKILL.md: it runs brainstorm → spec → plan → tasks, then routes back here once the plan is approved. Build directly only for a genuinely one-line / low-risk change. Method: ../sdd/SKILL.md.

First: confirm it's a Vite SPA, not a framework

Read package.json before giving any advice — it stops you applying SSR/RSC patterns to a client SPA.

Then pick the data layer (TanStack Query, always) and the router (React Router v7 library mode or TanStack Router).

Adjacent jobs route out: the type system itself (generics, discriminated unions, tsconfig theory) with no React shape → ../typescript/SKILL.md; visual design, tokens, spacing, button states → ../design/SKILL.md; writing the Vitest/RTL or E2E suite as the task → ../testing-web/SKILL.md; hosting the built dist/ → ../deployment/SKILL.md.

Component & state architecture

• Colocate state next to where it's used; only lift when two siblings must share it. Lifting earlier than needed is the #1 cause of re-render spread.
• Derive, don't duplicate. If a value is computable from props/state, compute it in render — never mirror it into another useState synced by an effect.
• Context for low-frequency, wide values (theme, current user, locale). It re-renders every consumer on every change.
• External store (Zustand) for high-frequency global state read by many components; subscribe with narrow selectors so only readers of a slice re-render.
• URL is state too. Filters, tabs, pagination belong in search params so they're shareable and survive reload.

// Bad: syncing a derived value into state with an effect → stale + extra render
const [fullName, setFullName] = useState("");
useEffect(() => { setFullName(`${first} ${last}`); }, [first, last]);

// Good: derive in render
const fullName = `${first} ${last}`;

Hooks discipline (React 19.2)

• useState for one or two independent values; useReducer when the next state depends on the previous one or several fields move together.
• The useEffect rule: effects exist to synchronize with a non-React external system (a subscription, a DOM node, a non-React widget). They are not for transforming data and not for fetching server data. If you can compute it in render or in an event handler, do that instead.
• useEffectEvent (stable in 19.2): extract the non-reactive part of an effect so it reads the latest props/state without being a dependency. Fixes the stale-closure / over-firing class of effect bug.

// Effect re-subscribes only when roomId changes, but still logs the latest theme.
const onConnected = useEffectEvent(() => log("connected", theme));
useEffect(() => {
  const c = connect(roomId);
  c.on("open", onConnected);
  return () => c.close();
}, [roomId]); // theme is NOT a dependency

• use(promise) reads a promise during render under <Suspense> + an error boundary. The promise must come from a cache (TanStack Query, a stable module cache) — never created inline, or you make a new promise every render and suspend forever.

// Bad: new promise each render → infinite suspense loop
function Profile({ id }: { id: string }) {
  const user = use(fetch(`/api/users/${id}`).then(r => r.json())); // ❌
}
// Good: the promise is owned by a cache (useSuspenseQuery, below)

• useTransition / useDeferredValue keep the UI responsive: mark a slow state update non-urgent so typing/clicks stay live.
• ref is a plain prop in React 19 — no forwardRef. The provider is <Context value={...}> (no .Provider). Refs may return a cleanup function.

Data fetching — TanStack Query, not useEffect (the headline rule)

Fetching server data in useEffect gives you waterfalls, race conditions, no caching, no dedupe, and double-fires under Strict Mode. Use TanStack Query v5 for all server state.

// Bad: the effect-as-fetch anti-pattern — races, no cache, refetches on every mount
const [user, setUser] = useState<User | null>(null);
useEffect(() => {
  fetch(`/api/users/${id}`).then(r => r.json()).then(setUser); // ❌ stale id, race, no error/loading
}, [id]);

// Good
const { data: user, isPending, isError } = useQuery({
  queryKey: ["user", id],          // identity + cache key + dedupe
  queryFn: () => getUser(id),       // typed fetcher
  staleTime: 60_000,                // 1 min "fresh" → no needless refetch
});

• Mutations invalidate the cache so reads refetch:

const qc = useQueryClient();
const remove = useMutation({
  mutationFn: deleteUser,
  onSuccess: () => qc.invalidateQueries({ queryKey: ["users"] }),
});

• useSuspenseQuery + <Suspense fallback> + an error boundary moves loading/error out of the component body and is the correct source for use()-style reads.
• Optimistic delete: onMutate snapshots + writes the expected state, onError rolls back, onSettled invalidates.
• Query-key factory, invalidateQueries vs setQueryData, infinite queries, prefetch, Zustand store + selectors, the full Bad→Good set → references/data-and-state.md.