react-advanced

What this skill does

# React Advanced: Core Patterns & Conventions (Cross-Platform)

This skill defines the rules, conventions, and architectural decisions for building modern
React applications with the TanStack ecosystem and XState. It is intentionally opinionated
to prevent common pitfalls and enforce patterns that scale.

These patterns work identically on **web and React Native**. For platform-specific patterns:

- **Web:** see `react-web-advanced` (TanStack Router, Start, Virtual)
- **React Native:** see `react-native-advanced` (Expo Router, FlashList, MMKV)

For detailed API documentation of any library mentioned here, use other appropriate tools
(documentation lookup, web search, etc.) — this skill focuses on **how** and **why** to
use these tools, not their full API surface.

## The useEffect Ban

Do not use `useEffect` for:

- **Data fetching** — use React Query (`useSuspenseQuery` / `useQuery`) or route loaders
- **Derived state** — compute during render or use `useMemo`
- **Syncing state with props** — use the prop directly, or reset with React `key`
- **Responding to user events** — put logic in event handlers
- **Subscribing to external stores** — use `useSyncExternalStore`
- **Complex async flows** — use XState machines with `invoke` / `fromPromise`

### Acceptable uses of useEffect

Legitimate cases:

1. **Synchronizing with non-React external systems** — DOM APIs, third-party widgets
   (maps, charts), imperative libraries that need mount/unmount lifecycle
2. **Browser/native API subscriptions with cleanup** — when `useSyncExternalStore` is too
   low-level for a one-off case (WebSocket connections, resize observers)
3. **Analytics/logging on mount** — fire-and-forget side effects with no state updates
4. **Bridging React Query data into XState** — the `useEffect` bridge pattern for
   pushing server state into a machine via events (see `references/xstate.md`)

### useMountEffect for mount-only effects

When you have a legitimate mount-only effect (cases 1–3 above), use a `useMountEffect`
helper instead of raw `useEffect(fn, [])`:

```typescript
// utils/useMountEffect.ts
import { useEffect, type EffectCallback } from "react";

// eslint-disable-next-line react-hooks/exhaustive-deps
const useMountEffect = (effect: EffectCallback) => useEffect(effect, []);

export default useMountEffect;
```

Usage:

```typescript
useMountEffect(() => {
  const plugin = $.myPlugin(ref.current);
  return () => {
    plugin.destroy();
  };
});
```

Why: raw `useEffect(fn, [])` triggers the `react-hooks/exhaustive-deps` lint rule and
makes the developer prove the empty array is intentional. `useMountEffect` makes the
"run once on mount" intent explicit in code and silences the warning correctly.

### What to use instead

| Instead of useEffect for...    | Use                                        |
| ------------------------------ | ------------------------------------------ |
| Fetching data                  | `useSuspenseQuery` + route loader prefetch |
| Consuming a Promise            | `use()` hook (React 19+) + `<Suspense>`    |
| Derived/computed values        | Direct computation or `useMemo`            |
| External store subscription    | `useSyncExternalStore`                     |
| Deferring expensive renders    | `useDeferredValue` / `useTransition`       |
| Complex async orchestration    | XState `invoke` with `fromPromise`         |
| Resetting state on prop change | React `key` prop on the component          |
| User-triggered side effects    | Event handlers directly                    |

---

## State Management Philosophy

### Server state vs client state — never mix them

**Server state** (data from APIs/databases) and **client state** (UI state existing only
in the client) are fundamentally different concerns. Mixing them causes stale data bugs,
duplication, and synchronization nightmares.

| Concern           | Owner         | Examples                                                    |
| ----------------- | ------------- | ----------------------------------------------------------- |
| Server data       | React Query   | Users, posts, products, orders                              |
| URL/route state   | Router        | Path params, search params (TanStack Router or Expo Router) |
| Complex UI flows  | XState        | Multi-step wizards, auth flows, drag-and-drop               |
| Shared client UI  | Zustand       | Theme, sidebar, selected items, global filters, preferences |
| Form fields       | TanStack Form | Input values, validation errors, submission                 |
| Schema validation | Zod           | Search params, form validators, API contracts               |
| Simple local UI   | `useState`    | Toggle, accordion expanded, input focus                     |

### Decision flowchart

```text
Is the data from a server / API?
  YES -> React Query (queryOptions + useSuspenseQuery)
  NO -> Is it in the URL / route params?
    YES -> Router (platform-specific: TanStack Router or Expo Router)
    NO -> Is it a complex multi-state flow (3+ states, async, guards)?
      YES -> XState (useMachine / createActorContext)
      NO -> Is it a form field?
        YES -> TanStack Form (with Zod validators)
        NO -> Is it shared across components / trees?
          YES -> Zustand (create store + selectors)
          NO -> useState / useReducer
```

### When to reach for XState over useState/useReducer

Use XState when:

- There are **3+ mutually exclusive states** with defined transitions
- **Async side effects** must be cancelled on state change (race conditions)
- The logic has **guards** (conditions that gate transitions)
- You need **parallel states** for independent concerns
- The flow needs to be **tested in isolation** from React
- Multiple steps with **back/forward navigation** (wizards)

Do not use XState for simple toggles, single boolean flags, or counter state. That is
`useState` territory.

---

## Architecture: Which Library Owns What

| Layer              | Library        | Responsibility                                      |
| ------------------ | -------------- | --------------------------------------------------- |
| Server state       | React Query    | Fetching, caching, invalidation, background refetch |
| Complex UI state   | XState         | State machines, actor model, flow orchestration     |
| Shared client UI   | Zustand        | Cross-component UI state, preferences, selections   |
| Form lifecycle     | TanStack Form  | Field values, validation, submission                |
| Schema validation  | Zod            | Search params, form validators, API contracts       |
| Data display       | TanStack Table | Headless sorting, filtering, pagination, grouping   |
| Testing            | Vitest + TL    | Unit, component, integration, machine testing       |
| Simple local state | useState       | Toggles, local inputs, component-scoped values      |

### The golden rule: `queryOptions` as single source of truth

Define query options once, import everywhere — loaders, components, invalidation:

```typescript
export const postsQueryOptions = queryOptions({
  queryKey: ["posts"],
  queryFn: fetchPosts,
  staleTime: 30_000,
});

export const postQueryOptions = (postId: string) =>
  queryOptions({
    queryKey: ["posts", postId],
    queryFn: () => fetchPost(postId),
    staleTime: 30_000,
  });
```

---

## Component Composition

### Compound components

Use Context-based compound components when a group of components shares implicit state.
The parent manages state; children consume it through context. Memoize the context value.

### Slots pattern

Use named props for slot-like composition (`header`, `footer`, `actions`). Avoid deeply
nested render-prop trees.

### Inversion of Control

When adding boolean props or branching logic to handle caller-specific behavior, push
that logic back to the caller via callbacks, reducers, or render functions. Three similar
if-statements is a signal to invert control.

---

## Common Pitfalls

1