tanstack-query-expert

TanStack Query Expert (v5 + TanStack Router/Start Edition)

English | Bahasa Indonesia

---

English

Orchestration & Integration

Connects and orchestrates with relevant domain skills like brainstorming, zero-to-prod-orchestrator, and project-context-mapper to ensure cohesive execution.

Description

Production-grade TanStack Query (v5) mastery for modern React (v18/19) and Next.js (App Router) applications. Covers declarative data fetching, advanced cache invalidation, optimistic UI updates, Suspense boundaries, SSR hydration, and the new TanStack Router + TanStack Start ecosystem for full-stack type-safe applications.

Trigger Conditions

• Refactoring data fetching logic (replacing useEffect + useState patterns).
• Designing query key factories (Array-based, strictly typed).
• Writing useMutation hooks with immediate Optimistic Updates.
• Implementing Infinite Scrolling (useInfiniteQuery).
• Using React Suspense with useSuspenseQuery.
• Integrating TanStack Query with Next.js App Router (Server Components prefetching + Client Boundary hydration).
• Building type-safe SPAs with TanStack Router (typed routes, route-level loaders).
• Building full-stack apps with TanStack Start (server functions, RSC-like patterns).

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 background refetch triggers. gcTime dictates how long inactive data stays in memory.
• Always use queryOptions() helper to co-locate query definition and reuse it across components and loaders.

Advanced Query Patterns

1. queryOptions() Helper — The 2026 Best Practice

Co-locate your query definition using queryOptions() to share it between components and route loaders:

import { queryOptions } from '@tanstack/react-query';

export const userQueryOptions = (userId: string) =>
  queryOptions({
    queryKey: ['users', userId],
    queryFn: () => fetchUser(userId),
    staleTime: 5 * 60 * 1000, // 5 minutes
  });

// In component:
const { data } = useQuery(userQueryOptions(userId));

// In TanStack Router loader:
export const Route = createFileRoute('/users/$userId')({
  loader: ({ context: { queryClient }, params }) =>
    queryClient.ensureQueryData(userQueryOptions(params.userId)),
  component: UserPage,
});