Nextjs Tanstack Query

Covers serializable query keys, staleTime tuning on prefetched queries to avoid immediate refetch, cache invalidation with invalidateQueries after writes, infinite scrolling/pagination, and DevTools setup gated to development only. Does not cover the Server Component boundary itself (nextjs-server-components) or core Next.js caching primitives like use cache (nextjs-16) — this skill is specifically about TanStack Query's client-side cache layer.

TanStack Query for Next.js

TanStack Query v5 provides powerful server state management with Next.js 16 integration.

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

1. explore-codebase - Analyze existing data fetching patterns
2. research-expert - Verify latest TanStack Query v5 docs
3. mcp__context7__query-docs - Check TanStack Query + Next.js patterns

After implementation, run sniper for validation.

Overview

When to Use

• Client-side data fetching with caching and revalidation
• Server-side prefetching with hydration to client
• Optimistic updates for mutations
• Infinite scrolling and pagination
• Real-time data synchronization

Why TanStack Query

Critical Rules

1. One QueryClient per request - Create in Server Component, share via context
2. Prefetch in Server Components - Use prefetchQuery for SSR data
3. HydrationBoundary required - Wrap client tree to transfer server cache
4. Query keys must be serializable - Arrays of strings/numbers only
5. staleTime on prefetched queries - Prevent immediate refetch on mount
6. Never use queryClient in Client Components directly - Use hooks

Installation

bun add @tanstack/react-query @tanstack/react-query-devtools

Best Practices

1. Prefetch on server - Avoid loading states for critical data
2. Set staleTime - Prevent unnecessary refetches after hydration
3. Collocate query keys - Define keys near their usage
4. Invalidate on mutation - Use invalidateQueries after writes
5. Error boundaries - Use throwOnError for critical queries
6. DevTools in dev only - Wrap in process.env.NODE_ENV check

Reference Guide