tanstack-query-best-practices

Set staleTime based on data volatility: 0 for real-time data, 30s-1min for notifications, 5min for user profiles, and Infinity for static content. Configure gcTime (default 5 minutes) to control how long inactive queries stay cached, using longer values for frequently revisited routes.

Use the onMutate callback to cancel outgoing queries, snapshot the previous cache with getQueryData, and apply the new state with setQueryData. Return the snapshot as context, then restore it in onError and call invalidateQueries in onSettled to sync with the server.

initialData is persisted to the cache and treated as real fetched data with staleTime applied, making it suitable for SSR. placeholderData is temporary, never cached, always triggers a background fetch, and sets isPlaceholderData to true, making it ideal for pagination and preview content.

Yes, TanStack Query supports SSR through the dehydrate/hydrate pattern with HydrationBoundary. Create a QueryClient per request on the server, set a higher staleTime to avoid double-fetching after hydration, and avoid gcTime of 0 to prevent hydration issues.

Duplicate page fetches happen when fetchNextPage is triggered without checking isFetching or isFetchingNextPage first. Guard scroll handlers and buttons with these flags, and ensure getNextPageParam returns undefined when no more pages exist.

Avoid retrying client errors like 404 and 403 since they will not resolve on retry. Use a custom retry function that returns false for 4xx status codes and limits retries for server errors, and keep mutation retry at 0 by default.