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, spawn 3 agents in parallel, one Agent call each with a name:

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

After implementation, run fuse-ai-pilot: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

Feature	Benefit
Server prefetching	Data ready on first render, no loading flash
Automatic caching	Deduplication, stale-while-revalidate
Mutations	Optimistic updates, rollback on error
DevTools	Visual cache inspection
TypeScript-first	Full type inference

---

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

Need	Reference
useQuery, useMutation	query-patterns.md
Server prefetching	hydration.md
QueryClient setup	hydration.md
Cache invalidation	query-patterns.md