Server State Management: TanStack Query v5 and Hydration

In modern web application engineering, one of the most persistent architectural anti-patterns has been the attempt to manage remote server data with client-side state managers (Redux, MobX, React Context).

Why This Matters#

Attempting to house remote backend data inside conventional client stores introduces three systemic flaws into production applications:

1. Network Waterfalls & Redundant Traffic: When five independent components on a page trigger data fetching inside useEffect, lacking deduplication, the browser fires five identical HTTP requests in parallel.
2. Data Staleness: Remote records change concurrently via other users and background jobs. A client store has no intrinsic awareness of database mutations, presenting stale data until the user forces a full page reload.
3. Complex Lifecycle Orchestration (Loading / Error / Cache / Garbage Collection): Manually orchestrating isLoading, isError, inactive cache expiration timers, in-flight request cancellation on route unmount, and optimistic rollbacks requires hundreds of lines of fragile boilerplate.

Mental Model#

Interactions between React components and the server cache rest upon four foundational architectural pillars:

• Request Deduplication: If multiple mounted components invoke useQuery simultaneously with identical query keys, exactly one network call is initiated. Every consuming component subscribes to the same shared promise inside QueryCache.
• Stale-While-Revalidate Protocol: The cache is governed by staleTime. While data remains fresh, it resolves instantly from memory without touching the network. Once stale, it resolves immediately from memory while quietly triggering a background revalidation request.
• Garbage Collection (gcTime): Governs memory deallocation after components unmount.
• Hierarchical Key Factories (Query Key Factory): Structuring keys as tuple arrays ['orders', 'detail', id] empowers both precise point updates and bulk cascading invalidations.

// TanStack Query Key Hierarchy
['orders']                       // All order-related queries
['orders', 'list']               // All order list queries
['orders', 'list', { status }]   // Filtered list query
['orders', 'detail', orderId]    // Specific order record

Practical Applications#

1. High-Frequency Enterprise Dashboards: Monitoring financial tickers, infrastructure telemetry, and fulfillment pipelines with window-focus background revalidation (refetchOnWindowFocus) and cross-tab synchronization.
2. Isomorphic Prefetching in Next.js App Router: Pre-populating cache (prefetchQuery) within Server Components and dehydrating into <HydrationBoundary> to eliminate Cumulative Layout Shift (CLS) and achieve instant First Contentful Paint.
3. High-Concurrence CRUD Interfaces: Task boards, CRM pipelines, and warehouse systems with optimistic drag-and-drop updates, immediate status transitions, and AbortSignal cancellation.
4. Infinite Scroll & Virtualized Feeds: Orchestrating bi-directional feeds via useInfiniteQuery (getNextPageParam, getPreviousPageParam) while preserving scroll coordinates upon back-navigation.

Architectural Pattern: Query Key Factory#

Scattering loose array literals like ['users', userId, 'posts'] across UI components breeds typographical errors and incomplete cache invalidations. Production systems enforce the Query Key Factory pattern:

/**
 * Strongly typed hierarchical cache key factory.
 * Enforces safe granular updates and prefix-based cascading invalidations.
 */
export const orderKeys = {
  all: ['orders'] as const,
  lists: () => [...orderKeys.all, 'list'] as const,
  list: (filters: { status?: string; page?: number }) =>
    [...orderKeys.lists(), filters] as const,
  details: () => [...orderKeys.all, 'detail'] as const,
  detail: (id: string) => [...orderKeys.details(), id] as const,
  metrics: (dateRange: { from: string; to: string }) =>
    [...orderKeys.all, 'metrics', dateRange] as const,
};

// Invalidation examples:
// queryClient.invalidateQueries({ queryKey: orderKeys.all }) -> invalidates all order queries
// queryClient.invalidateQueries({ queryKey: orderKeys.lists() }) -> invalidates only lists
// queryClient.invalidateQueries({ queryKey: orderKeys.detail('42') }) -> invalidates order #42

Server Prefetching and HydrationBoundary in Next.js#

In Next.js App Router, data is fetched upstream inside a Server Component using a request-scoped QueryClient, serialized via dehydrate, and handed to the client tree using HydrationBoundary:

import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query';
import { orderKeys } from '@/api/queryKeys';
import { fetchOrderById } from '@/api/orders';
import { OrderDetailsView } from '@/components/OrderDetailsView';

interface PageProps {
  params: Promise<{ id: string }>;
}

export default async function OrderPage({ params }: PageProps) {
  const { id } = await params;
  
  // Create an isolated QueryClient per incoming request (Request-Scoped)
  const queryClient = new QueryClient();

  // Prefetch data into the server cache (Node.js/Edge runtime)
  await queryClient.prefetchQuery({
    queryKey: orderKeys.detail(id),
    queryFn: ({ signal }) => fetchOrderById(id, signal),
  });

  return (
    // Dehydrated state is provided to client components without request waterfalls
    <HydrationBoundary state={dehydrate(queryClient)}>
      <OrderDetailsView orderId={id} />
    </HydrationBoundary>
  );
}

'use client';

import { useQuery } from '@tanstack/react-query';
import { orderKeys } from '@/api/queryKeys';
import { fetchOrderById } from '@/api/orders';

export function OrderDetailsView({ orderId }: { orderId: string }) {
  // Data resolves INSTANTLY from the HydrationBoundary cache with zero skeleton flicker!
  const { data: order, status, isFetching } = useQuery({
    queryKey: orderKeys.detail(orderId),
    queryFn: ({ signal }) => fetchOrderById(orderId, signal),
    staleTime: 60 * 1000, // Data remains fresh for 1 minute
  });

  if (status === 'pending') {
    return <div className="animate-pulse p-4">Loading skeleton...</div>;
  }

  if (status === 'error') {
    return <div className="text-red-400 p-4">Failed to load order.</div>;
  }

  return (
    <div className="p-6 border border-border rounded-xl bg-bg-surface">
      <div className="flex items-center justify-between">
        <h1 className="text-xl font-bold font-sans">Order #{order.id}</h1>
        {isFetching && (
          <span className="text-xs text-accent-cyan animate-pulse">
            Syncing...
          </span>
        )}
      </div>
      <p className="mt-2 text-text-muted">Status: {order.status}</p>
      <p className="text-text-muted">Total: ${order.totalAmount}</p>
    </div>
  );
}

Optimistic Updates with Deterministic Rollback#

The Optimistic Update pattern is implemented across three discrete lifecycle steps in useMutation:

1. onMutate: Cancel in-flight queries, snapshot existing cache entries, and synchronously apply optimistic data via setQueryData.
2. onError: Restore previous cache snapshot if network fails.
3. onSettled: Invalidate affected keys to reconcile with authoritative database state.

Comparative Analysis: staleTime vs. gcTime#

Production Artifact: Resilient Optimistic Mutation Hook#

import { useMutation, useQueryClient } from '@tanstack/react-query';

export type TaskStatus = 'TODO' | 'IN_PROGRESS' | 'DONE';

export interface TaskItem {
  readonly id: string;
  readonly title: string;
  readonly status: TaskStatus;
  readonly updatedAt: string;
}

export interface UpdateTaskPayload {
  readonly taskId: string;
  readonly nextStatus: TaskStatus;
}

interface MutationContext {
  previousTasks?: TaskItem[];
}

export const taskKeys = {
  all: ['tasks'] as const,
  lists: () => [...taskKeys.all, 'list'] as const,
};

async function mutateTaskStatusApi(
  payload: UpdateTaskPayload,
  signal?: AbortSignal
): Promise<TaskItem> {
  const response = await fetch(`/api/tasks/${payload.taskId}/status`, {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ status: payload.nextStatus }),
    signal,
  });

  if (!response.ok) {
    throw new Error(`Failed to update task status: HTTP ${response.status}`);
  }

  return (await response.json()) as TaskItem;
}

export function useUpdateTaskStatus() {
  const queryClient = useQueryClient();

  return useMutation<TaskItem, Error, UpdateTaskPayload, MutationContext>({
    mutationFn: (payload) => mutateTaskStatusApi(payload),

    // 1. Optimistic Update Phase
    onMutate: async (newTodoPayload) => {
      // Cancel active list refetches to prevent race condition overrides
      await queryClient.cancelQueries({ queryKey: taskKeys.lists() });

      // Snapshot existing cache state for rollback guarantee
      const previousTasks = queryClient.getQueryData<TaskItem[]>(taskKeys.lists());

      // Optimistically write updated status
      if (previousTasks) {
        queryClient.setQueryData<TaskItem[]>(
          taskKeys.lists(),
          previousTasks.map((task) =>
            task.id === newTodoPayload.taskId
              ? {
                  ...task,
                  status: newTodoPayload.nextStatus,
                  updatedAt: new Date().toISOString(),
                }
              : task
          )
        );
      }

      // Return context containing previous state for onError
      return { previousTasks };
    },

    // 2. Rollback Phase
    onError: (_err, _variables, context) => {
      if (context?.previousTasks) {
        queryClient.setQueryData(taskKeys.lists(), context.previousTasks);
      }
    },

    // 3. Final Reconciliation Phase
    onSettled: () => {
      void queryClient.invalidateQueries({ queryKey: taskKeys.lists() });
    },
  });
}

Common Pitfalls#

// ❌ ANTIPATTERN: Fresh QueryClient created on every render cycle!
export function BadAppProvider({ children }: { children: React.ReactNode }) {
  const queryClient = new QueryClient(); // CACHE DESTROYED ON EVERY RENDER!
  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
}

// ✅ PRODUCTION CONTRACT: Singleton instance on client, per-request instance on server
function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 60 * 1000,
      },
    },
  });
}

let browserQueryClient: QueryClient | undefined = undefined;

function getQueryClient() {
  if (typeof window === 'undefined') {
    // Server: Always create a fresh client per request
    return makeQueryClient();
  }
  // Browser: Reuse persistent singleton client
  if (!browserQueryClient) browserQueryClient = makeQueryClient();
  return browserQueryClient;
}

export function GoodAppProvider({ children }: { children: React.ReactNode }) {
  const queryClient = getQueryClient();
  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
}

// ❌ ANTIPATTERN: Request cannot be aborted when unmounted
useQuery({
  queryKey: ['users', id],
  queryFn: () => fetch(`/api/users/${id}`).then((res) => res.json()),
});

// ✅ PRODUCTION CONTRACT: Pass AbortSignal to native fetch
useQuery({
  queryKey: ['users', id],
  queryFn: ({ signal }) =>
    fetch(`/api/users/${id}`, { signal }).then((res) => {
      if (!res.ok) throw new Error('Network error');
      return res.json();
    }),
});

// ❌ ANTIPATTERN: gcTime purges cache after 10s, despite 5m fresh window!
useQuery({
  queryKey: ['analytics'],
  queryFn: fetchAnalytics,
  staleTime: 5 * 60 * 1000, // 5 minutes
  gcTime: 10 * 1000,        // 10 seconds (Critical configuration flaw!)
});

// ✅ PRODUCTION CONTRACT: gcTime MUST ALWAYS be greater than or equal to staleTime
useQuery({
  queryKey: ['analytics'],
  queryFn: fetchAnalytics,
  staleTime: 5 * 60 * 1000, // 5 minutes
  gcTime: 15 * 60 * 1000,   // 15 minutes
});

// ❌ ANTIPATTERN: Direct in-place mutation of cache reference
const { data: user } = useQuery({ queryKey: ['user', id], queryFn: fetchUser });
const onClick = () => {
  if (user) {
    user.name = 'New Name'; // FORBIDDEN: Mutating immutable cache object!
  }
};

// ✅ PRODUCTION CONTRACT: Immutable update via queryClient.setQueryData
const queryClient = useQueryClient();
const onClickGood = () => {
  queryClient.setQueryData(['user', id], (oldUser: User | undefined) => {
    if (!oldUser) return undefined;
    return { ...oldUser, name: 'New Name' };
  });
};