State Management

作者 asyrafhussin1aa0ff717c10MIT86 個星標收錄於 2026年10月8日更新於 2026年10月8日儲存庫6 週前更新

React Query and Zustand patterns for state management. Use when implementing data fetching, caching, mutations, or client-side state. Triggers on tasks involving useQuery, useMutation, Zustand stores, caching, or state management.

AI 產生的概覽

React Query v5 與 Zustand v5 狀態管理的參考模式,涵蓋資料擷取、快取、變更與用戶端儲存。

功能
此技能提供 TanStack Query v5(伺服器狀態)與 Zustand v5(用戶端狀態)的程式碼模式參考指南。內容涵蓋 v5 破壞性變更、查詢鍵、useQuery 與 useMutation 用法、樂觀更新、快取與失效,以及搭配中介軟體的 store 建立方式。rules/ 目錄下另有 26 個以上的獨立規則檔案,提供詳細說明與程式碼範例。
適用情境
適用於以 React Query 實作資料擷取、快取、變更或樂觀更新的情境,也適用於建立與持久化 Zustand 用戶端 store。亦可用於在 React 應用程式中合併使用這兩個函式庫。
執行需求
不含指令碼,僅為說明文件與規則檔案。所述模式假定 React 專案已安裝 @tanstack/react-query v5(可選用其 devtools)與 zustand v5。

State Management with React Query + Zustand

Version 1.1.0 | TanStack Query v5 | Zustand v5 | March 2026

Note: This document provides comprehensive patterns for AI agents and LLMs working with TanStack Query v5 and Zustand v5. All examples are verified against v5 APIs. Optimized for automated refactoring, code generation, and state management best practices.

v5 Breaking Changes (Quick Reference)

TanStack Query v5:

  • cacheTime → gcTime
  • keepPreviousData option → placeholderData: keepPreviousData (imported helper)
  • isPreviousData → isPlaceholderData
  • onSuccess/onError/onSettled removed from useQuery — still valid on useMutation
  • suspense: true on useQuery removed → use useSuspenseQuery

Zustand v5:

  • shallow as 2nd arg removed → useShallow from zustand/shallow
  • Selectors returning new references need useShallow to avoid infinite loops

Security: Persist Middleware

Never persist auth tokens, passwords, or secrets to localStorage/sessionStorage. Use partialize to persist only non-sensitive state. Manage tokens via HttpOnly cookies.


Comprehensive patterns for server state (React Query) and client state (Zustand). Contains 26+ rules for efficient data fetching and state management.

When to Apply

Reference these guidelines when:

  • Fetching data from APIs
  • Managing server state and caching
  • Handling mutations and optimistic updates
  • Creating client-side stores
  • Combining React Query with Zustand

Rule Categories by Priority

PriorityCategoryImpactPrefix
1React Query BasicsCRITICALrq-
2Zustand Store PatternsCRITICALzs-
3Caching & InvalidationHIGHcache-
4Mutations & UpdatesHIGHmut-
5Optimistic UpdatesMEDIUMopt-
6DevTools & DebuggingMEDIUMdev-
7Advanced PatternsLOWadv-

Quick Reference

1. React Query Basics (CRITICAL)

  • rq-setup - QueryClient and Provider setup
  • rq-usequery - Basic useQuery patterns
  • rq-querykeys - Query key organization
  • rq-loading-error - Handle loading and error states
  • rq-enabled - Conditional queries

2. Zustand Store Patterns (CRITICAL)

  • zs-create-store - Create basic store
  • zs-typescript - TypeScript store patterns
  • zs-selectors - Efficient selectors
  • zs-actions - Action patterns
  • zs-persist - Persist state to storage

3. Caching & Invalidation (HIGH)

  • cache-stale-time - Configure stale time
  • cache-gc-time - Configure garbage collection
  • cache-invalidation - Invalidate queries
  • cache-prefetch - Prefetch data
  • cache-initial-data - Set initial data

4. Mutations & Updates (HIGH)

  • mut-usemutation - Basic useMutation
  • mut-callbacks - onSuccess, onError callbacks
  • mut-invalidate - Invalidate after mutation
  • mut-update-cache - Direct cache updates

5. Optimistic Updates (MEDIUM)

  • opt-basic - Basic optimistic updates
  • opt-rollback - Rollback on error
  • opt-variables - Use mutation variables

6. DevTools & Debugging (MEDIUM)

  • dev-react-query - React Query DevTools
  • dev-zustand - Zustand DevTools
  • dev-debugging - Debug strategies

7. Advanced Patterns (LOW)

  • adv-infinite-queries - Infinite scrolling
  • adv-parallel-queries - Parallel requests
  • adv-dependent-queries - Dependent queries
  • adv-query-zustand - Combine RQ with Zustand

React Query Patterns

Setup

tsx
// lib/queryClient.tsimport { QueryClient } from '@tanstack/react-query'
export const queryClient = new QueryClient({  defaultOptions: {    queries: {      staleTime: 1000 * 60 * 5, // 5 minutes      gcTime: 1000 * 60 * 30,   // 30 minutes (formerly cacheTime)      retry: 1,      refetchOnWindowFocus: false,    },  },})
// App.tsximport { QueryClientProvider } from '@tanstack/react-query'import { ReactQueryDevtools } from '@tanstack/react-query-devtools'import { queryClient } from './lib/queryClient'
function App() {  return (    <QueryClientProvider client={queryClient}>      <Router />      <ReactQueryDevtools initialIsOpen={false} />    </QueryClientProvider>  )}

Query Keys Factory

tsx
// lib/queryKeys.tsexport const queryKeys = {  // All posts  posts: {    all: ['posts'] as const,    lists: () => [...queryKeys.posts.all, 'list'] as const,    list: (filters: PostFilters) =>      [...queryKeys.posts.lists(), filters] as const,    details: () => [...queryKeys.posts.all, 'detail'] as const,    detail: (id: number) => [...queryKeys.posts.details(), id] as const,  },
  // All users  users: {    all: ['users'] as const,    detail: (id: number) => [...queryKeys.users.all, id] as const,    posts: (userId: number) => [...queryKeys.users.all, userId, 'posts'] as const,  },}

useQuery Hook

tsx
// hooks/usePosts.tsimport { useQuery } from '@tanstack/react-query'import { queryKeys } from '@/lib/queryKeys'import { fetchPosts, fetchPost } from '@/api/posts'
export function usePosts(filters?: PostFilters) {  return useQuery({    queryKey: queryKeys.posts.list(filters ?? {}),    queryFn: () => fetchPosts(filters),  })}
export function usePost(id: number) {  return useQuery({    queryKey: queryKeys.posts.detail(id),    queryFn: () => fetchPost(id),    enabled: !!id, // Only run if id exists  })}
// Usage in componentfunction PostList() {  const { data: posts, isLoading, error } = usePosts()
  if (isLoading) return <Spinner />  if (error) return <Error message={error.message} />
  return (    <ul>      {posts?.map((post) => (        <li key={post.id}>{post.title}</li>      ))}    </ul>  )}

useMutation Hook

tsx
// hooks/useCreatePost.tsimport { useMutation, useQueryClient } from '@tanstack/react-query'import { queryKeys } from '@/lib/queryKeys'import { createPost } from '@/api/posts'
export function useCreatePost() {  const queryClient = useQueryClient()
  return useMutation({    mutationFn: createPost,    onSuccess: (newPost) => {      // Invalidate and refetch posts list      queryClient.invalidateQueries({        queryKey: queryKeys.posts.lists(),      })    },    onError: (error) => {      console.error('Failed to create post:', error)    },  })}
// Usagefunction CreatePostForm() {  const { mutate, isPending } = useCreatePost()
  const handleSubmit = (data: CreatePostData) => {    mutate(data)  }
  return (    <form onSubmit={handleSubmit}>      {/* form fields */}      <button disabled={isPending}>        {isPending ? 'Creating...' : 'Create'}      </button>    </form>  )}

Optimistic Updates

tsx
export function useUpdatePost() {  const queryClient = useQueryClient()
  return useMutation({    mutationFn: updatePost,    onMutate: async (updatedPost) => {      // Cancel outgoing refetches      await queryClient.cancelQueries({        queryKey: queryKeys.posts.detail(updatedPost.id),      })
      // Snapshot previous value      const previousPost = queryClient.getQueryData(        queryKeys.posts.detail(updatedPost.id)      )
      // Optimistically update      queryClient.setQueryData(        queryKeys.posts.detail(updatedPost.id),        updatedPost      )
      return { previousPost }    },    onError: (err, updatedPost, context) => {      // Rollback on error      queryClient.setQueryData(        queryKeys.posts.detail(updatedPost.id),        context?.previousPost      )    },    onSettled: (data, error, variables) => {      // Refetch after settle      queryClient.invalidateQueries({        queryKey: queryKeys.posts.detail(variables.id),      })    },  })}

Zustand Patterns

Basic Store

tsx
// stores/useCounterStore.tsimport { create } from 'zustand'
interface CounterState {  count: number  increment: () => void  decrement: () => void  reset: () => void}
export const useCounterStore = create<CounterState>((set) => ({  count: 0,  increment: () => set((state) => ({ count: state.count + 1 })),  decrement: () => set((state) => ({ count: state.count - 1 })),  reset: () => set({ count: 0 }),}))
// Usagefunction Counter() {  const { count, increment, decrement } = useCounterStore()
  return (    <div>      <span>{count}</span>      <button onClick={increment}>+</button>      <button onClick={decrement}>-</button>    </div>  )}

Store with TypeScript and Middleware

tsx
// stores/useAuthStore.tsimport { create } from 'zustand'import { persist, devtools } from 'zustand/middleware'
interface User {  id: number  name: string  email: string}
interface AuthState {  user: User | null  isAuthenticated: boolean  login: (user: User) => void  logout: () => void}
// ✅ Never persist tokens to localStorage — use HttpOnly cookies server-sideexport const useAuthStore = create<AuthState>()(  devtools(    persist(      (set) => ({        user: null,        isAuthenticated: false,
        login: (user) =>          set({            user,            isAuthenticated: true,          }),
        logout: () =>          set({            user: null,            isAuthenticated: false,          }),      }),      {        name: 'auth-storage',        // Only persist display info and auth flag — tokens must NOT be included        partialize: (state) => ({          user: state.user,          isAuthenticated: state.isAuthenticated,        }),      }    )  ))

Selectors for Performance

tsx
// Use selectors to prevent unnecessary re-rendersfunction UserName() {  // Only re-renders when user.name changes  const name = useAuthStore((state) => state.user?.name)  return <span>{name}</span>}
// Multiple selectorsfunction UserInfo() {  const user = useAuthStore((state) => state.user)  const isAuthenticated = useAuthStore((state) => state.isAuthenticated)
  if (!isAuthenticated) return <LoginButton />  return <span>{user?.name}</span>}

Combining React Query + Zustand

tsx
// Server state: React Query (what comes from API)const { data: posts } = usePosts()
// Client state: Zustand (UI state)const { selectedPostId, selectPost } = useUIStore()
// Use togetherconst selectedPost = posts?.find((p) => p.id === selectedPostId)

How to Use

Read individual rule files for detailed explanations and code examples:

rules/rq-usequery.mdrules/rq-query-keys.mdrules/rq-mutation-setup.mdrules/rq-optimistic-updates.mdrules/zs-create-store.mdrules/zs-persist.mdrules/rq-query-invalidation.mdrules/rq-prefetching.md

References

React Query (TanStack Query)

  1. TanStack Query Documentation
  2. React Query Overview
  3. Queries Guide
  4. Mutations Guide
  5. Query Keys Guide
  6. Optimistic Updates
  7. Infinite Queries
  8. Paginated Queries
  9. React Query DevTools

Zustand

  1. Zustand Demo
  2. Zustand GitHub
  3. Getting Started
  4. TypeScript Guide
  5. Persisting Store Data
  6. Zustand Recipes

License

This skill is provided as-is for educational and development purposes. React Query is MIT licensed by TanStack. Zustand is MIT licensed by Poimandres (pmnd.rs).

來源與署名

來源:asyrafhussin/agent-skills位於skills/state-management提交1aa0ff7

授權條款: MIT

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架