TanStack Knowledge Graph — TanStack Atlas

Focus by product

Fetch machine graph

Lesson 05Let the loader warm the Query cacheRouter decides when navigation happens while Query owns the cache. Connect them with one shared queryOptions object.

05

loader / query

Navigation and async cache

Router coordinates navigation while Query owns caching and refetch lifecycles.

Engineering doc / decisionRouter loader or Query?Choose Loader, Query, or both from navigation criticality and data lifecycle needs.Engineering doc / recipePrefetch Query from a route loaderCreate a request-scoped QueryClient for SSR and reuse one queryOptions contract in the loader and useSuspenseQuery.

Lesson 06Write back from a Server FunctionValidate input at the network boundary, model write state with a mutation, then immutably update Query cache from the server response.

06

mutation / invalidation

Writes and cache consistency

Validate the write boundary, then update or invalidate cache from the server response.

Engineering doc / recipeUpdate cache from a mutation responseUse setQueryData when the write response contains the complete entity; invalidate when the correct cache cannot be derived.

Lesson 10Define when data is freshSeparate staleTime from gcTime and co-locate keys, fetchers, and time policy in shared queryOptions.

10

staleTime / gcTime

Cache freshness policy

Define independently when data becomes stale and how long inactive queries remain cached.

Engineering doc / contractDefine a Query freshness contractSet staleTime from data volatility and decide inactive-cache gcTime independently.

Lesson 13Propagate Query cancellation to the networkConsume the AbortSignal supplied to queryFn so obsolete fetches stop and cancellation state remains predictable.

13

AbortSignal / fetch

Async request cancellation

Propagate Query AbortSignal to the network layer to stop obsolete I/O and preserve cache semantics.

Engineering doc / contractConsume Query AbortSignalPass the queryFn signal into the request layer so cancellation stops I/O with explicit cache-revert semantics.

Lesson 15Keep infinite lists bounded and recoverableDefine pagination with initialPageParam, cursors, and maxPages while preserving the pages and pageParams structure.

15

pageParam / maxPages

Bounded infinite pagination

Let server cursors drive page params while preserving pages, pageParams, and memory bounds.

Engineering doc / recipeBuild a bounded cursor Infinite QueryUse one queryKey for the full list, let server cursors drive pageParam, and bound cache and refetch cost with maxPages.

Lesson 16Isolate and stream Query state across SSRUse the Router SSR Query integration for dehydration, hydration, and streaming while creating an isolated cache per server request.

16

SSR / hydration

Query SSR and streaming hydration

Isolate QueryClient per server request and choose blocking, hydration, or streaming for critical data.

Engineering doc / contractConfigure Query SSR and streaming hydrationCreate a QueryClient per SSR request, use the Router integration for dehydration and hydration, and classify blocking versus streaming queries.

Lesson 17Make optimistic updates safe to roll backChoose UI-only pending output or a cache-level update, then handle failure and concurrency with cancellation, snapshots, rollback, and revalidation.

17

onMutate / rollback

Optimistic consistency and rollback

Use cancellation, snapshots, immutable writes, and revalidation so immediate feedback converges on server truth.

Engineering doc / recipeImplement a rollback-safe optimistic updateCancel conflicting refetches, snapshot cache, write an immutable draft, roll back on failure, and revalidate on settlement.