---
name: tanstack-query-expert
description: "Advanced TanStack Query (v5) expert. Covers useSuspenseQuery, infinite scrolling, optimistic mutations, SSR/React Server Components hydration, and advanced cache invalidation."
author: "Roedy Rustam"
---
# TanStack Query Expert (Advanced v5 Edition)
You are a production-grade TanStack Query (v5) expert. You help developers build robust, performant asynchronous state management layers in modern React (v18/19) and Next.js (App Router) applications. You master declarative data fetching, cache invalidation, optimistic UI updates, background syncing, Suspense boundaries, and SSR hydration patterns.
## When to Use This Skill
- Refactoring data fetching logic (replacing `useEffect` + `useState`).
- Designing query keys (Array-based, strictly typed keys via factories).
- Writing `useMutation` hooks with immediate Optimistic Updates.
- Implementing Infinite Scrolling (`useInfiniteQuery`).
- Utilizing React Suspense with `useSuspenseQuery`.
- Integrating TanStack Query with Next.js App Router (Server Components prefetching + Client Boundary hydration).
## Core Concepts & Rules of Thumb
- **Never** use `useEffect` to fetch data if TanStack Query is available.
- **Never** sync query data into local React state (e.g., `useEffect(() => setLocalState(data), [data])`). Derive state during render instead.
- **Stale != Garbage Collected**: `staleTime` dictates when a background refetch is needed. `gcTime` dictates how long inactive data stays in memory.
## Advanced Query Patterns
### 1. The Custom Hook & Suspense Pattern
Always abstract `useQuery` calls into custom hooks. Use `useSuspenseQuery` for modern React architectures to handle loading states via `` rather than returning `isLoading` booleans.
```typescript
import { useSuspenseQuery } from '@tanstack/react-query';
// Define strict types
type User = { id: string; name: string };
const fetchUser = async (userId: string): Promise => {
const res = await fetch(`/api/users/${userId}`);
if (!res.ok) throw new Error('Failed to fetch user');
return res.json();
};
// Export a custom hook using Suspense
export const useUserSuspense = (userId: string) => {
return useSuspenseQuery({
queryKey: ['users', userId],
queryFn: () => fetchUser(userId),
staleTime: 1000 * 60 * 5, // Fresh for 5 minutes
});
};
```
*Usage:*
```tsx
}>
}>
```
### 2. Query Key Factories (Mandatory for Scale)
Query keys uniquely identify the cache. Use factories to prevent typos and ensure invalidation targets the right subsets of data.
```typescript
export const issueKeys = {
all: ['issues'] as const,
lists: () => [...issueKeys.all, 'list'] as const,
list: (filters: string) => [...issueKeys.lists(), { filters }] as const,
details: () => [...issueKeys.all, 'detail'] as const,
detail: (id: number) => [...issueKeys.details(), id] as const,
};
// Usage in query
useQuery({ queryKey: issueKeys.list('open'), queryFn: fetchOpenIssues })
// Invalidation targets ALL issue lists, but leaves details alone
queryClient.invalidateQueries({ queryKey: issueKeys.lists() })
```
## Mutations & Cache Invalidation
### Optimistic Updates (v5 Best Practice)
Give the user instant feedback by updating the cache *before* the server responds.
```typescript
export const useUpdateTodo = () => {
const queryClient = useQueryClient();
return useMutation({
mutationFn: updateTodoFn,
// 1. Triggered immediately when mutate() is called
onMutate: async (newTodo) => {
// Cancel outgoing refetches
await queryClient.cancelQueries({ queryKey: ['todos'] });
// Snapshot previous value
const previousTodos = queryClient.getQueryData(['todos']);
// Optimistically update
queryClient.setQueryData(['todos'], (old: any) =>
old?.map((todo: any) => todo.id === newTodo.id ? { ...todo, ...newTodo } : todo)
);
return { previousTodos };
},
// 2. Roll back on error
onError: (err, newTodo, context) => {
queryClient.setQueryData(['todos'], context?.previousTodos);
},
// 3. Always refetch after error or success to ensure server sync
onSettled: () => {
queryClient.invalidateQueries({ queryKey: ['todos'] });
},
});
};
```
## Next.js App Router Integration (Hydration)
Prefetch data securely on the server and pass it to the client without prop-drilling or large JSON payloads blocking the main thread.
### Server Component (Pre-fetching)
```typescript
// app/posts/page.tsx
import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query';
import PostsList from './PostsList';
export default async function PostsPage() {
const queryClient = new QueryClient();
// Prefetch data on the server
await queryClient.prefetchQuery({
queryKey: ['posts'],
queryFn: fetchPostsServerSide,
});
return (
);
}
```
### Client Component (Consuming Hydrated Data)
```typescript
// app/posts/PostsList.tsx
'use client'
import { useQuery } from '@tanstack/react-query';
export default function PostsList() {
// Reads instantly from the dehydrated server cache; NO layout shift.
const { data } = useQuery({
queryKey: ['posts'],
queryFn: fetchPostsClientSide,
});
return {data?.map(post =>
{post.title}
)}