菜单
Configure TanStack Query (React Query) with QueryClient, provider, devtools, and optimal defaults. SHARED skill for both TanStack Start (SSR) and TanStack Router (SPA).
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | tanstack-react-query-setup |
| description | Configure TanStack Query (React Query) with QueryClient, provider, devtools, and optimal defaults. SHARED skill for both TanStack Start (SSR) and TanStack Router (SPA). |
This skill covers setting up TanStack Query (formerly React Query) in TanStack Start or TanStack Router projects. TanStack Query provides powerful asynchronous state management for data fetching, caching, and synchronization.
Important: This skill works for both:
Install the core package and devtools:
bun add @tanstack/react-query @tanstack/react-query-devtools
Or with npm:
npm install @tanstack/react-query @tanstack/react-query-devtools
Create src/lib/query-client.ts with optimal defaults:
import { QueryClient } from '@tanstack/react-query'
export const queryClient = new QueryClient({
defaultOptions: {
queries: {
// Time before data is considered stale (5 minutes)
staleTime: 1000 * 60 * 5,
// Time before inactive queries are garbage collected (10 minutes)
gcTime: 1000 * 60 * 10,
// Retry failed requests 3 times with exponential backoff
retry: 3,
retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
// Refetch on window focus in production
refetchOnWindowFocus: process.env.NODE_ENV === 'production',
// Don't refetch on mount if data is fresh
refetchOnMount: false,
},
mutations: {
// Retry failed mutations once
retry: 1,
},
},
})
| Option | Default | Description |
|---|---|---|
staleTime | 5 minutes | How long data is considered fresh |
gcTime | 10 minutes | How long inactive data is kept in cache |
retry | 3 | Number of retry attempts on failure |
retryDelay | Exponential | Delay between retry attempts |
refetchOnWindowFocus | true (prod) | Refetch when user returns to tab |
refetchOnMount | false | Refetch when component mounts |
Create src/components/query-provider.tsx:
import { QueryClientProvider } from '@tanstack/react-query'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
import { queryClient } from '~/lib/query-client'
type QueryProviderProps = {
children: React.ReactNode
}
export function QueryProvider({ children }: QueryProviderProps) {
return (
<QueryClientProvider client={queryClient}>
{children}
<ReactQueryDevtools initialIsOpen={false} position="bottom" />
</QueryClientProvider>
)
}
The devtools panel provides:
Options:
initialIsOpen: Start with devtools open/closedposition: 'top' | 'bottom' | 'left' | 'right'buttonPosition: Where to place the toggle buttonUpdate src/routes/__root.tsx:
import { createRootRoute, Outlet } from '@tanstack/react-router'
import { Meta, Scripts } from '@tanstack/react-start'
import { QueryProvider } from '~/components/query-provider'
import '../app.css'
export const Route = createRootRoute({
head: () => ({
meta: [
{ charSet: 'utf-8' },
{ name: 'viewport', content: 'width=device-width, initial-scale=1' },
],
}),
component: () => (
<html>
<head>
<Meta />
</head>
<body>
<QueryProvider>
<Outlet />
</QueryProvider>
<Scripts />
</body>
</html>
),
})
Update your entry point src/main.tsx:
import React from 'react'
import ReactDOM from 'react-dom/client'
import { RouterProvider, createRouter } from '@tanstack/react-router'
import { QueryProvider } from '~/components/query-provider'
import { routeTree } from './routeTree.gen'
import './app.css'
const router = createRouter({ routeTree })
declare module '@tanstack/react-router' {
interface Register {
router: typeof router
}
}
const rootElement = document.getElementById('root')!
if (!rootElement.innerHTML) {
const root = ReactDOM.createRoot(rootElement)
root.render(
<React.StrictMode>
<QueryProvider>
<RouterProvider router={router} />
</QueryProvider>
</React.StrictMode>
)
}
Create a simple query to test the setup:
import { useQuery } from '@tanstack/react-query'
export function UserProfile() {
const { data, isLoading, error } = useQuery({
queryKey: ['user', 'profile'],
queryFn: async () => {
const response = await fetch('/api/user/profile')
if (!response.ok) throw new Error('Failed to fetch user')
return response.json()
},
})
if (isLoading) return <div>Loading...</div>
if (error) return <div>Error: {error.message}</div>
return (
<div>
<h1>{data.name}</h1>
<p>{data.email}</p>
</div>
)
}
For production optimizations, create separate configs:
// src/lib/query-client.ts
import { QueryClient } from '@tanstack/react-query'
const isDevelopment = process.env.NODE_ENV === 'development'
export const queryClient = new QueryClient({
defaultOptions: {
queries: {
staleTime: isDevelopment ? 0 : 1000 * 60 * 5,
gcTime: isDevelopment ? 1000 * 60 * 5 : 1000 * 60 * 10,
retry: isDevelopment ? 1 : 3,
refetchOnWindowFocus: !isDevelopment,
refetchOnMount: isDevelopment,
},
},
})
For server-side rendering with TanStack Start, configure hydration:
// src/lib/query-client.ts
import { QueryClient, isServer } from '@tanstack/react-query'
function makeQueryClient() {
return new QueryClient({
defaultOptions: {
queries: {
staleTime: 1000 * 60 * 5,
gcTime: 1000 * 60 * 10,
},
},
})
}
let browserQueryClient: QueryClient | undefined = undefined
export function getQueryClient() {
if (isServer) {
// Server: always create a new QueryClient
return makeQueryClient()
} else {
// Browser: reuse singleton QueryClient
if (!browserQueryClient) browserQueryClient = makeQueryClient()
return browserQueryClient
}
}
Update provider for SSR:
// src/components/query-provider.tsx
import { QueryClientProvider } from '@tanstack/react-query'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
import { getQueryClient } from '~/lib/query-client'
type QueryProviderProps = {
children: React.ReactNode
}
export function QueryProvider({ children }: QueryProviderProps) {
const queryClient = getQueryClient()
return (
<QueryClientProvider client={queryClient}>
{children}
<ReactQueryDevtools initialIsOpen={false} />
</QueryClientProvider>
)
}
After setup, verify:
useQueryExample verification component:
import { useQuery } from '@tanstack/react-query'
export function HealthCheck() {
const { data, isLoading, dataUpdatedAt } = useQuery({
queryKey: ['health'],
queryFn: async () => {
const response = await fetch('https://api.github.com/zen')
return response.text()
},
})
return (
<div className="p-4 border rounded">
<h2 className="font-bold">TanStack Query Health Check</h2>
{isLoading ? (
<p>Loading...</p>
) : (
<>
<p className="mt-2">{data}</p>
<p className="text-xs text-muted-foreground mt-2">
Last updated: {new Date(dataUpdatedAt).toLocaleTimeString()}
</p>
</>
)}
</div>
)
}
Cause: Component rendered outside QueryProvider
Solution: Ensure QueryProvider wraps your component tree in __root.tsx
Cause: staleTime is too low
Solution: Increase staleTime in QueryClient config
Cause: Devtools only show in development
Solution: Check NODE_ENV and ensure devtools are included
Cause: Server and client QueryClient instances differ
Solution: Use getQueryClient() pattern for SSR
bun add @tanstack/react-query-persist-client
import { QueryClient } from '@tanstack/react-query'
import { persistQueryClient } from '@tanstack/react-query-persist-client'
import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'
const queryClient = new QueryClient({
defaultOptions: {
queries: {
gcTime: 1000 * 60 * 60 * 24, // 24 hours
},
},
})
const persister = createSyncStoragePersister({
storage: window.localStorage,
})
persistQueryClient({
queryClient,
persister,
})
import { QueryClient } from '@tanstack/react-query'
import { toast } from '~/components/ui/use-toast'
const queryClient = new QueryClient({
defaultOptions: {
queries: {
onError: (error) => {
toast({
variant: 'destructive',
title: 'Query Error',
description: error.message,
})
},
},
mutations: {
onError: (error) => {
toast({
variant: 'destructive',
title: 'Mutation Error',
description: error.message,
})
},
},
},
})
your-project/
├── src/
│ ├── components/
│ │ └── query-provider.tsx # Query provider wrapper
│ ├── lib/
│ │ └── query-client.ts # QueryClient configuration
│ ├── routes/ # TanStack routes
│ │ └── __root.tsx # Root with QueryProvider
│ └── app.css # Global styles
├── tsconfig.json
└── vite.config.ts
After setup:
tanstack-react-query-patterns skill)tanstack-react-query-mutations skill)tanstack-client-api-layer skill)tanstack-client-auth skill)Master multi-agent orchestration using Claude Code's TeammateTool and Task system. Use when coordinating multiple agents, running parallel code reviews, creating pipeline workflows with dependencies, building self-organizing task queues, or any task benefiting from divide-and-conquer patterns.
API client setup with fetch wrapper, error handling, authentication headers, and React Query integration for TanStack Start/Router.
Token-based authentication for TanStack Client (SPA) apps including login/logout, protected routes, auth context, token storage, and route guards. SHARED skill for both TanStack Start (client-only mode) and TanStack Router.
Mutation patterns with useMutation, optimistic updates, cache invalidation, and rollback strategies. SHARED skill for both TanStack Start (SSR) and TanStack Router (SPA).
Query patterns with queryOptions factory, key conventions, prefetching strategies, and type-safe reusable query definitions. SHARED skill for both TanStack Start (SSR) and TanStack Router (SPA).
Configure Tailwind CSS v4 and shadcn/ui with theming, dark mode, and CSS variables. SHARED skill for both TanStack Start (SSR) and TanStack Router (SPA).