react-advanced（React 高级）

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, []):

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

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.

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

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.
2. Storing server data in client state — putting API responses in Zustand/Redux means you own caching and invalidation. Use React Query instead.
3. Duplicating URL state in useState — use your router's search/param hooks directly.
4. Using React Query AND XState for the same data — React Query owns fetching/caching. XState receives data via events and handles orchestration only.
5. Calling React hooks inside XState machines — hooks only work in React components. Use fromPromise in machines, bridge data via useEffect events.
6. Array indices as keys — use stable IDs (item.id). Index keys cause incorrect state association on reorder/insert/delete.
7. Defining components inside components — creates new component types each render, forcing React to unmount/remount. Define at module level.
8. 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.
9. 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: