菜单
Sets up server-state with TanStack Query (caching, mutations, optimistic updates, hydration) and picks the right client-state tool; used when wiring data fetching or untangling state.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/Sir-chawakorn/sanook-cli --skill manage-client-server-state命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
Gets machine-parseable JSON out of an LLM reliably — prefer provider-enforced grammar (OpenAI `response_format:{type:"json_schema",strict:true}`, Anthropic tool-calling / `tool_choice:{type:"tool"}`, Gemini `responseSchema`) over a "respond in JSON" prompt, define the contract once as a Pydantic/Zod model and validate every response (never trust the string), use constrained decoding / grammars for open weights (Outlines, llguidance, llama.cpp GBNF, vLLM `guided_json`), keep schemas SHALLOW with required fields + enums + `additionalProperties:false`, and build a repair-and-retry loop that handles refusals, `length`/`max_tokens` truncation, and streaming partial JSON (`partial-json-parser`). Schema-guided generation eliminates parse-error retries; validate-and-repair is the backstop, not the primary mechanism.
Builds production data grids that stay fast and accessible at 10k–1M+ rows — decide server-side vs client-side sort/filter/paginate by the dataset-fits-in-memory test (client only under ~10k rows, otherwise push to the API and treat the table as a controlled view of server state), ROW-VIRTUALIZE with TanStack Virtual or react-window so only the visible window mounts (fixed estimateSize, overscan 5–10, measureElement for dynamic rows, contain:strict, and a real scroll container — never table-layout:auto over thousands of rows), build the headless logic with TanStack Table v8 (or AG Grid when you need pinning/grouping/enterprise out of the box), add column resize/reorder/pin, inline edit with optimistic update + rollback on error, row selection with a stable rowId, full keyboard nav with roving tabindex over an ARIA grid (role=grid/row/gridcell, aria-sort, aria-rowcount/aria-rowindex so virtualization stays announced), position:sticky headers, streaming CSV export that doesn't block the main thread, and explici
Builds semantic/vector search — pick an embedding model + dimensionality (and whether to truncate Matryoshka dims) and the matching distance metric (cosine/dot/L2, normalize to unit length so cosine == dot and IP is correct), an ANN index with the recall/latency/memory tradeoff understood (HNSW M/efConstruction/efSearch for low-latency RAM-resident; IVF-PQ nlist/nprobe/PQ for billion-scale compressed; flat/exact for <100k) in pgvector/Qdrant/Milvus/FAISS/Pinecone, chunking + overlap + per-chunk metadata for filtering, HYBRID retrieval fusing BM25 + dense by Reciprocal Rank Fusion (RRF, k≈60) not score addition, a cross-encoder/Cohere reranker over the top-50→k, correct pre-filter-vs-ANN interaction (filterable HNSW, not post-filter that starves k), and offline eval with recall@k / nDCG@10 / MRR against a labeled qrels set. Quantize (scalar/PQ) only after measuring recall loss; tune efSearch/nprobe to a recall target, not a guess.
基于 SOC 职业分类
正在显示 SKILL.md
| name | manage-client-server-state |
| description | Sets up server-state with TanStack Query (caching, mutations, optimistic updates, hydration) and picks the right client-state tool; used when wiring data fetching or untangling state. |
| when_to_use | When the user wires data fetching/caching, mentions TanStack Query / React Query, useEffect fetch waterfalls, optimistic UI, SSR hydration, or choosing a state manager (Zustand/Context/Redux). |
Reach for this skill when the task involves any of:
useQuery, useMutation, QueryClient).useEffect and stuffs results into useState (manual loading/error flags, refetch-on-prop-change, fetch waterfalls).Skip / hand off if the task is purely form validation (use build-form-validation) or component scaffolding/markup (component skill). This skill is about where state lives and how it syncs, not UI structure.
First principle, state the line out loud before coding: Server state ≠ client state. Server state is async, owned by the backend, shared, and can go stale (lists, user profile, search results) → TanStack Query. Client state is synchronous, owned by the UI, local (modal open, active tab, form draft, theme) → useState / Zustand / Context. Most "state is a mess" bugs are these two being managed by the same tool.
Classify every piece of state first. Grep the file/feature for useState, useEffect, useContext, dispatch. For each, ask: does the value originate from an API/DB? → server state, migrate to TanStack Query. Is it ephemeral UI? → leave as client state. Do NOT migrate UI toggles into Query, and do NOT keep fetched data in useState.
Provider + client setup (once per app). Create one QueryClient and wrap the tree in <QueryClientProvider>. In Next.js App Router, the client MUST be created inside a "use client" component via useState(() => new QueryClient()) (not a module-level singleton) so each request/user gets its own cache. Set sane defaults: staleTime 30–60s for most reads (0 means "always refetch on mount/focus" — usually not what you want), keep gcTime (v5; was cacheTime) default 5min unless memory-bound.
Replace useEffect+fetch with useQuery. Pattern:
const { data, isPending, isError, error } = useQuery({
queryKey: ['todos', { status, page }], // serializable, hierarchical
queryFn: ({ signal }) => fetchTodos({ status, page, signal }),
staleTime: 30_000,
})
Delete the manual loading/error/data useState and the useEffect. Pass signal into fetch for auto-cancel. queryKey strategy: array form, broad→narrow (['todos'] → ['todos', id] → ['todos', { filters }]). Every variable the queryFn reads MUST appear in the key — missing deps = stale data served for the wrong params. Centralize keys in a queryKeys factory object to avoid typos and make invalidation greppable.
queryKey missing a queryFn dependency → wrong/stale data shown when params change. Every variable used in queryFn must be in the key.new QueryClient() in Next.js → cache leaks across requests/users on the server (one user sees another's data). Create it inside useState/per-request.v5 rename trap: cacheTime → gcTime, isLoading → isPending (for "no data yet"), useQuery no longer takes positional args (options object only), callbacks onSuccess/onError removed from useQuery (still on useMutation). If you see those on a query, it's v4 code.staleTime: 0 (default) + refetchOnWindowFocus → app hammers the API on every tab switch. Set a real staleTime for reads that don't need to be live.cancelQueries → an in-flight background refetch resolves after your optimistic setQueryData and overwrites it → UI flickers back. Always cancelQueries in onMutate.['todos'], client useQuery(['todos', filters]) → no cache hit, refetch + flash. Keys must match exactly.invalidateQueries with an over-narrow key → sibling queries stay stale. Invalidate at the right prefix level.fetch(/axios call inside useEffect writing to useState remains for server data; those are now useQuery/useMutation.cacheTime, useQuery({ onSuccess })) left.fresh/stale status, and no duplicate keys fetching the same data.Mutations + invalidation. Use useMutation for writes. After success, invalidate the affected reads so they refetch:
const qc = useQueryClient()
useMutation({
mutationFn: updateTodo,
onSuccess: () => qc.invalidateQueries({ queryKey: ['todos'] }),
})
invalidateQueries({ queryKey: ['todos'] }) matches all keys prefixed by ['todos'] — that's the lever the hierarchical key design buys you. Prefer invalidation over manually hand-editing the cache unless you're doing optimistic updates.
Optimistic updates (only where latency is felt — toggles, likes, reorder). The four-callback contract:
useMutation({
mutationFn: toggleTodo,
onMutate: async (next) => {
await qc.cancelQueries({ queryKey: ['todos'] }) // stop in-flight refetch clobbering us
const prev = qc.getQueryData(['todos']) // snapshot for rollback
qc.setQueryData(['todos'], (old) => applyOptimistic(old, next))
return { prev } // context passed to onError
},
onError: (_e, _next, ctx) => qc.setQueryData(['todos'], ctx?.prev), // rollback
onSettled: () => qc.invalidateQueries({ queryKey: ['todos'] }), // reconcile w/ server
})
All three of cancelQueries / snapshot+rollback / onSettled invalidate are required — drop any one and you get flicker, lost rollback, or permanent drift from the server.
SSR / RSC hydration (Next.js App Router). In the server component: create a request-scoped QueryClient, await queryClient.prefetchQuery({ queryKey, queryFn }), then render <HydrationBoundary state={dehydrate(queryClient)}> wrapping the client component. The client component calls useQuery with the identical queryKey — it reads the dehydrated cache, no refetch, no loading flash. Mismatched keys between prefetch and useQuery = silent double-fetch on the client; this is the #1 hydration bug, verify keys are byte-identical.
Pick the client-state tool (the non-server state from step 1):
| Need | Use |
|---|---|
| Low-frequency, rarely-changing (theme, locale, auth user object) | Context |
| Cross-cutting, frequently-updated, shared across distant components (cart, wizard, filters) | Zustand |
| Local to one subtree | keep useState / useReducer, lift only as far as needed |
| Complex shared logic + time-travel/devtools/middleware genuinely needed | Redux Toolkit (default to NOT this) |
| Do not reach for Redux by reflex, and do not put server data in any of these — that's step 3's job. |
Kill prop drilling + unnecessary re-renders. If a prop is threaded through 3+ layers only to reach a leaf, move it to Context or Zustand. For Zustand, always select narrowly — useStore((s) => s.cart.count), never useStore((s) => s.cart) or the whole store, or every store change re-renders the component. For Context, split into multiple providers (e.g. separate ThemeContext and AuthContext) so a change to one doesn't re-render consumers of the other; memoize the provider value.