Tanstack Query Architecture

TanStack Query Architecture

This skill manages server state using TanStack Query (React Query / Svelte Query). It ensures aggressive caching, prevents unnecessary network spam, and governs strict optimistic UI updates.

When to Use

• Use when fetching, caching, synchronizing, or updating server state in frontend frameworks.
• Use when implementing infinite scrolling or paginated data fetching.
• NOT for global client state (like a dark mode toggle); use standard Context/Stores for that.

Core Process

Phase 1: Query Keys & Caching

• Treat Query Keys strictly as dependency arrays. If the query function relies on a variable (e.g., userId), that variable MUST be in the query key array ['user', userId].
• Define explicit staleTime and gcTime. The default staleTime is 0, which means every re-render causes a background fetch. Configure this to a sensible default (e.g., 1000 * 60 * 5 for 5 minutes).

Phase 2: Optimistic Updates

• When mutating data, update the UI immediately before the server responds to create a fast UX.
• In the onMutate callback, cancel outgoing queries for that key, snapshot the previous value, and manually set the query data using queryClient.setQueryData.
• In onError, rollback the cache to the snapshot.

Phase 3: SSR Hydration

• When using Next.js or SvelteKit, fetch data on the server during SSR and use HydrationBoundary or dehydrate() to pass the cache to the client to prevent a loading spinner on the initial paint.

Common Rationalizations

Red Flags

• Utilizing useEffect or Svelte $effect to perform raw fetch calls.
• Missing staleTime configuration on QueryClient, causing massive API spam.

Verification

Before finalizing the query architecture:

• All API fetches occur exclusively through useQuery or createQuery.
• Mutations implement optimistic cache updates and rollback mechanisms.
• Query keys correctly reflect all variables used inside the fetch function.