React Query + Zustand Clean Architecture Patterns Skill

React Query + Zustand Clean Architecture Patterns

State management architecture for React/Next.js applications using TanStack Query v5 and Zustand 5.

The Boundary

React Query cache  ─── server state (single source of truth)
useState           ─── local form / ephemeral component state
Zustand            ─── client-only UI state (NO server mirrors)

The anti-pattern this replaces:

API → React Query → useEffect hydration → Zustand items[] → Components
        fetch              mirror               store          read

This pattern creates two sources of truth, requires sync*ToStore() indirection, and causes stale-state bugs when components read from Zustand instead of the cache.

When to Apply

Apply these patterns when:

Writing or reviewing useQuery / useMutation hooks
Writing or reviewing Zustand store slices
Implementing optimistic updates with rollback
Reading server data inside async functions (stale closure risk)
Deciding whether a piece of data belongs in RQ cache or Zustand
Refactoring useEffect hydration that writes to Zustand

Pattern Index

| Priority | Pattern | Impact | Reference File | |----------|---------|--------|---------------| | 1 | State boundary — what goes where | CRITICAL | references/core-principle.md | | 2 | staleTime: Infinity + gcTime strategy | HIGH | references/stale-time-gc.md | | 3 | Adapter hook with select optimization | HIGH | references/adapter-hook.md | | 4 | Cache helpers — imperative read/write | HIGH | references/cache-helpers.md | | 5 | Optimistic update + automatic rollback | HIGH | references/optimistic-updates.md | | 6 | Zustand session slice for client-only state | MEDIUM | references/zustand-session-slice.md | | 7 | Anti-patterns to avoid | CRITICAL | references/anti-patterns.md |

Quick Reference

Reading server data in async functions

// WRONG — stale closure from Zustand mirror
const post = useAppStore.getState().posts.find(p => p.id === postId);

// CORRECT — always fresh from React Query cache
const post = getEntityFromCache(queryClient, postId);

Optimistic update with rollback

await withOptimisticUpdate(
  queryClient,
  postId,
  (prev) => ({ ...prev, tags }),   // 1. update cache immediately
  () => updatePost({ postId, tags }), // 2. persist in background
  // auto-rollback to snapshot on error
);

Component: select only what you need

// Re-renders only when title changes, not on any field change
const { data: title } = usePostData(postId, {
  select: (d) => d.title,
});

Zustand: client-only state only

// WRONG — server data mirror
store.addPost(postFromServer);        // called in useEffect after fetch
store.updatePost(id, serverResponse); // called after mutation success

// CORRECT — transient client state only
store.setDraftContent(postId, content); // local editor state
store.setActiveView('editor');          // UI navigation state

References

TanStack Query v5 Docs: https://tanstack.com/query/v5/docs
Zustand 5 Docs: https://zustand.docs.pmnd.rs/
"Does React Query replace Redux/Zustand?": https://tanstack.com/query/v5/docs/framework/react/guides/does-this-replace-client-state-managers

Agent Skills: React Query + Zustand Clean Architecture Patterns

Install this agent skill to your local

Skill Files