TanStack Query v5 data fetching guide 2026

TanStack Query manages server state on the client: caching, background refetching, retries and mutations. It is a good fit for interactive dashboards and client-heavy apps; it is unnecessary for a page that can fetch on the server.

What matters in practice

• Use the Next.js integration to hydrate the cache from server-rendered data.
• Do not use it as a global state manager for UI state.

How to implement it

1. Create the provider. Put a QueryClientProvider around the client tree.
2. Define query keys. One factory per feature so invalidation is predictable.
3. Fetch on the server where possible. Hydrate the client cache with initial data.
4. Set freshness. Use a realistic staleTime for the data, not a global default.
5. Handle mutations. Invalidate affected queries and show optimistic feedback where safe.
6. Observe. Log query errors and slow requests; add retries only for transient failures.

A working example

const queryKeys = {
products: (filters: Filters) => ["products", filters] as const,
};
export function useProducts(filters: Filters) {
return useQuery({
queryKey: queryKeys.products(filters),
queryFn: () => fetchProducts(filters),
staleTime: 30_000,
});
}

Production checklist

Area	Check
Provider	One client per request in SSR; one per app in the browser
Keys	Stable, serialisable and scoped by feature
Freshness	staleTime and gcTime set per data type
Mutations	Invalidation or optimistic update with rollback
Hydration	Server data dehydrated into the client cache
Errors	Retry policy and user-visible error states

Common mistakes

• Using array index or object identity in a query key.
• Setting staleTime: Infinity for data that changes.
• Duplicating server state into a global store.
• Forgetting to invalidate after a mutation.

When this is the wrong tool

Every tool has a boundary. If the team is small, the use case is simple and the operational cost is high, a simpler stack may be better. The right choice is the one you can debug, secure and hand over without the original author.

Rollout plan

1. Prove one slice. Use TanStack Query v5 for one real route or feature, not the whole product.
2. Set the boundary. Write down what stays on the server, what runs on the client and how data crosses the boundary.
3. Add the safety net. Types, validation, tests and error handling around the new slice.
4. Measure. Check bundle size, latency, error rate and the developer experience before expanding.
5. Document and hand over. Record the pattern, the pitfalls and the version constraints.

Testing strategy

Layer	What to test	Why
Types	Strict compile and no unjustified any	Catches contract drift early
Unit	Pure logic, validation and state transitions	Fast feedback
Integration	API, database and auth boundaries	Most production failures live here
End-to-end	The critical user journey	Proves the wiring
Operations	Logs, errors, retries and rollback	A release is not finished at deploy

Operational checklist

• Pin the runtime and dependency versions; test upgrades in a branch.
• Keep secrets on the server and validate every external payload.
• Add structured logs with a request ID, but never log tokens or personal data.
• Set a performance or bundle budget and check it in CI.
• Write a short runbook for the most likely failure.

Sources and further reading

• TanStack Query documentation (tanstack.com)
• Next.js data fetching (nextjs.org)
• React documentation (react.dev)

Related reading

• TypeScript best practices
• Next.js deployment guide
• Web application development