tanstack-query-best-practices

Always use arrays organized hierarchically from general to specific: entity, then ID, then filters or sub-resources, such as ['todos', 5, 'comments']. 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, apply the change with setQueryData, and return the snapshot as context. Roll back in onError using that context, then invalidate in onSettled to resync 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. Prefetch queries on the server with a per-request QueryClient, pass dehydrate(queryClient) into a HydrationBoundary, and consume the data client-side with useSuspenseQuery. Set a nonzero staleTime on the server to avoid an immediate client refetch.

The mutation likely did not invalidate the affected queries. In onSuccess, call queryClient.invalidateQueries with the specific query keys impacted, including lists, detail views, and any cross-entity queries that display the changed data.

Use placeholderData for temporary previews that should not persist to cache, such as showing list data while a detail query fetches. Use initialData for authoritative data like SSR results, paired with initialDataUpdatedAt so stale calculations are correct.