tanstack-query-best-practices

Always use arrays organized hierarchically from general to specific: entity type first, then ID, then filters or sub-resources. Include every variable the query function depends on, and use query key factories for consistency in larger applications.

Cancel outgoing queries in onMutate, snapshot the previous cache, update it with setQueryData, and return the snapshot as context. Roll back in onError using that context, then invalidate queries in onSettled to sync with the server.

staleTime controls how long fetched data is considered fresh before background refetching, while gcTime controls how long inactive query data stays in cache before garbage collection. Set staleTime based on data volatility and gcTime based on how often users revisit the data.

Yes, use the dehydrate/hydrate pattern: prefetch queries into a new QueryClient on the server, pass dehydrate(queryClient) to HydrationBoundary, and consume the data with useSuspenseQuery on the client. Create a fresh QueryClient per request to avoid sharing data between users.

The mutation likely did not invalidate all affected queries. In onSuccess, invalidate every query key whose data could change, including lists, detail views, counts, and cross-entity queries, using hierarchical keys for precise targeting.

Use placeholderData for temporary previews like list-item data shown while fetching details, since it never persists to cache. Use initialData for authoritative data such as SSR-fetched content, since it is cached and respects staleTime.