React Advanced

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

1. Browser/native API subscriptions with cleanup — when useSyncExternalStore is too

low-level for a one-off case (WebSocket connections, resize observers)

1. Analytics/logging on mount — fire-and-forget side effects with no state updates
2. 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, []):

// 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:

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+) + ` | | 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

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:

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. Derived state in useEffect — computing values in an effect and storing in useState

causes double renders. Compute during render or use useMemo.

1. Storing server data in client state — putting API responses in Zustand/Redux means

you own caching and invalidation. Use React Query instead.

1. Duplicating URL state in useState — use your router's search/param hooks directly.

1. Using React Query AND XState for the same data — React Query owns fetching/caching.

XState receives data via events and handles orchestration only.

1. Calling React hooks inside XState machines — hooks only work in React components.

Use fromPromise in machines, bridge data via useEffect events.

1. Array indices as keys — use stable IDs (item.id). Index keys cause incorrect

state association on reorder/insert/delete.

1. Defining components inside components — creates new component types each render,

forcing React to unmount/remount. Define at module level.

1. Context for high-frequency state — Context re-renders all consumers on every

change. Use Zustand with selectors for shared rapidly-changing values (see references/zustand.md), or local state if component-scoped.

1. Not using .catch() on Zod search param schemas — .default() only handles

missing keys; .catch() also handles invalid values from malformed URLs.

---

Reference Files

Read the relevant reference file when working with a specific library:

| File | When to read | | --------------------------- | --------------------------------------------------------------------- | | references/react-query.md | Query patterns, mutations, cache, Suspense integration | | references/table.md | Column defs, sorting, filtering, pagination, server-side ops | | references/form.md | Field validation, arrays, schema validation, performance | | references/xstate.md | State machines, actors, auth flows, wizards, React integration | | references/zustand.md | Shared client UI state, selectors, slices, middleware, vanilla stores | | references/zod.md | Schema validation, v4 API, Form integration, error handling | | references/testing.md | Vitest setup, Testing Library, MSW, testing Query/Form/XState | | references/integration.md | Combining libraries: Zustand+XState, Query+XState bridge |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: trancong12102
• Source: trancong12102/agentskills
• License: MIT

Install and usage instructions live in the source repository linked above.