TanStack Query: Cache Management

TanStack Query: Cache Management

Directly read, write, and remove cache entries with QueryClient methods

When to Use

• Updating related cache entries after a mutation without an extra network request
• Pre-populating the cache with data received from a WebSocket or server-sent event
• Removing cached data when it is known to be invalid (e.g., after logout)
• Inspecting cached values in tests to assert cache state after operations
• Implementing advanced patterns like cache federation or cross-query updates

Instructions

1. Use queryClient.setQueryData(key, updaterOrValue) to write a value directly to the cache — the query does not refetch.
2. Use queryClient.getQueryData(key) to read a cached value synchronously — returns undefined if not cached.
3. Use queryClient.cancelQueries({ queryKey }) before manual cache writes to prevent in-flight fetches from overwriting your change.
4. Use queryClient.removeQueries({ queryKey }) to evict cache entries entirely — they refetch fresh on next mount.
5. Use queryClient.clear() to clear the entire cache — call this on logout to remove all user data.
6. Use queryClient.getQueriesData(filter) to bulk-read multiple cache entries matching a filter.
7. Use updater functions in setQueryData for immutable updates — receive current value, return new value.

// Real-time cache update from WebSocket
function useLivePostUpdates() {
  const queryClient = useQueryClient();

  useEffect(() => {
    const ws = new WebSocket('/ws/posts');

    ws.onmessage = (event) => {
      const updatedPost: Post = JSON.parse(event.data);

      // Update the specific post detail
      queryClient.setQueryData(postKeys.detail(updatedPost.id), updatedPost);

      // Update the post in all list caches
      queryClient.setQueriesData<PostsPage>({ queryKey: postKeys.lists() }, (old) => {
        if (!old) return old;
        return {
          ...old,
          posts: old.posts.map((p) => (p.id === updatedPost.id ? updatedPost : p)),
        };
      });
    };

    return () => ws.close();
  }, [queryClient]);
}

// Logout — clear all user data from cache
function useLogout() {
  const queryClient = useQueryClient();
  const router = useRouter();

  return async () => {
    await fetch('/api/auth/logout', { method: 'POST' });
    queryClient.clear(); // remove all cached data
    router.push('/login');
  };
}

// Seeding cache after create mutation — avoid refetch
const { mutate: createPost } = useMutation({
  mutationFn: (data: CreatePostInput) =>
    fetch('/api/posts', { method: 'POST', body: JSON.stringify(data) }).then((r) => r.json()),
  onSuccess: (newPost: Post) => {
    // Add to detail cache directly
    queryClient.setQueryData(postKeys.detail(newPost.id), newPost);
    // Invalidate lists — server determines list membership
    queryClient.invalidateQueries({ queryKey: postKeys.lists() });
  },
});

Details

TanStack Query's cache is a Map-like structure keyed by serialized query keys. setQueryData, getQueryData, and removeQueries give direct programmatic access to this cache outside the normal fetch lifecycle.

setQueryData vs invalidateQueries: setQueryData writes a value and marks the query as fresh (it will not refetch until staleTime expires). invalidateQueries marks the query as stale and triggers a background refetch. Use setQueryData when you have the correct server response in hand (e.g., from a create mutation); use invalidateQueries when you know data has changed but do not have the new value.

setQueriesData for list updates: When a single entity update needs to reflect in multiple list queries (e.g., filtered views), use setQueriesData(filter, updater) to update all matching caches in one call. The filter uses the same matching logic as invalidateQueries.

Observer pattern: Use queryClient.getQueryCache().subscribe(callback) to observe all cache changes. This is useful for syncing query state to external systems (analytics, debug logging). Unsubscribe on cleanup.

Type safety: getQueryData<T>(key) returns T | undefined. Always handle the undefined case — the cache may not have the value if it was never fetched or was garbage collected.

Testing assertions: In tests, call queryClient.getQueryData(key) after mutations to assert that the cache was updated correctly — without needing to render a component and inspect the DOM.

Source

https://tanstack.com/query/latest/docs/reference/QueryClient

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.