Instructions

When to Use

• Use for TanStack Query v5 + RSC hydration without double fetch.
• Prefer next-server-patterns when the question is server-only data.
• Prefer server-caching-handbook for tag/TTL stampedes.

Use TanStack Query v5 (@tanstack/react-query) with Next.js App Router without fighting RSC.

1. Provider: wrap client subtree that needs queries - usually a providers.tsx client component imported from layout.tsx; do not wrap entire app in client unless necessary.
2. Keys: stable serializable arrays; include locale and filters; never embed secrets in keys.
3. Server prefetch: when RSC fetches initial data, pass dehydrated state to client HydrationBoundary + prefetchQuery - client useQuery must use same key and compatible queryFn or rely on hydrated data.
4. Defaults: set sensible staleTime (e.g. 30s–5m for dashboards); avoid refetchOnWindowFocus storm on sensitive forms - tune per query.
5. Mutations: onSuccess invalidate minimal key prefixes; optimistic updates only with rollback plan.
6. Errors: surface with boundaries (error-loading-not-found skill); do not leak server error bodies to toast without sanitization.

Outcomes

• Provider file outline + one useQuery + one RSC prefetch example names only (no full app).