TanStack Query: The Complete Guide to Server State Management in React

TanStack Query (formerly React Query) is a server state management library that eliminates the complexity of synchronizing server data with your UI. Unlike client state solutions like Redux or Zustand, TanStack Query specializes in managing asynchronous server state—the data that lives on your backend and needs to be fetched, cached, and synchronized.

Traditional approaches to server state in React lead to boilerplate-heavy code with manual caching, background refetching, and complex loading/error state management. TanStack Query solves these problems through intelligent caching, automatic background updates, and a declarative API that handles race conditions and stale data gracefully.

💡 Server state is asynchronous by nature—data fetches take time, can fail, and become stale. TanStack Query embraces these realities rather than abstracting them away.

Core Concepts: QueryClient and Stale-While-Revalidate

At the heart of TanStack Query is the QueryClient, which manages the cache and coordinates network requests. The library implements a stale-while-revalidate strategy: cached data is served immediately while background requests refresh stale data.

TypeScript

import { QueryClient } from '@tanstack/react-query';
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5, // 5 minutes
      gcTime: 1000 * 60 * 10, // 10 minutes (formerly cacheTime)
      retry: 3,
      refetchOnWindowFocus: true,
      refetchOnReconnect: true,
    },
  },
});
// Wrap your app
import { QueryClientProvider } from '@tanstack/react-query';
function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <YourApp />
    </QueryClientProvider>
  );
}

Query Keys and Lifecycle

Query keys are the primary identifiers for cached data. They support scalars, arrays, and nested objects. The query lifecycle follows: fetching → fresh → stale → inactive → garbage collected.

TypeScript

// Query key patterns
const queryKeys = {
  users: ['users'] as const,
  user: (id: number) => ['users', id] as const,
  userPosts: (userId: number) => ['users', userId, 'posts'] as const,
  post: (postId: number, userId: number) => ['posts', postId, userId] as const,
};
// Using query keys
function useUser(id: number) {
  return useQuery({
    queryKey: queryKeys.user(id),
    queryFn: () => fetchUser(id),
    // Query lifecycle states:
    // - loading: initial fetch
    // - stale: data older than staleTime
    // - inactive: no components observing
    // - garbage collected: inactive beyond gcTime
  });
}

📌 Query keys should be serializable and stable—avoid inline objects or arrays that create new references on every render.

useQuery Deep Dive

The useQuery hook is the primary way to fetch and manage server state. It accepts a queryKey and queryFn, along with numerous configuration options for fine-grained control over caching, refetching, and data transformation.

TypeScript

import { useQuery, UseQueryOptions } from '@tanstack/react-query';
interface User {
  id: number;
  name: string;
  email: string;
}
function useUser(
  userId: number,
  options?: Omit<UseQueryOptions<User, Error>, 'queryKey' | 'queryFn'>
) {
  return useQuery<User, Error>({
    queryKey: queryKeys.user(userId),
    queryFn: async ({ signal }) => {
      const response = await fetch(`/api/users/${userId}`, { signal });
      if (!response.ok) throw new Error('Failed to fetch user');
      return response.json();
    },
    enabled: !!userId, // Only run if userId exists
    staleTime: 1000 * 60 * 5,
    gcTime: 1000 * 60 * 10,
    refetchOnWindowFocus: false,
    retry: (failureCount, error) => {
      // Don't retry on 4xx errors
      if (error.message.includes('4')) return false;
      return failureCount < 3;
    },
    select: (data) => ({
      ...data,
      displayName: `${data.name} (${data.email})`
    }),
    ...options,
  });
}

🎯 Use the select option to derive data or transform responses without affecting cache keys—this prevents unnecessary re-renders when only derived data changes.

Dependent Queries

TypeScript

// Dependent queries - second query depends on first
function useUserWithPosts(userId: number) {
  const { data: user, isLoading: userLoading } = useUser(userId);
  
  const { data: posts } = useQuery<Post[], Error>({
    queryKey: ['posts', user?.id],
    queryFn: () => fetchPostsByUser(user!.id),
    enabled: !!user, // Only run when user exists
  });
  
  return { user, posts, isLoading: userLoading };
}
// Parallel queries with different keys
function useDashboardData() {
  const userQuery = useUser(1);
  const postsQuery = usePosts();
  const statsQuery = useStats();
  
  return {
    user: userQuery.data,
    posts: postsQuery.data,
    stats: statsQuery.data,
    isLoading: userQuery.isLoading || postsQuery.isLoading || statsQuery.isLoading,
  };
}

useMutation: Handling Data Mutations

While useQuery handles data fetching, useMutation manages data modifications. It provides lifecycle callbacks for optimistic updates, error handling, and cache invalidation.

TypeScript

import { useMutation, useQueryClient } from '@tanstack/react-query';
interface CreateUserDto {
  name: string;
  email: string;
}
function useCreateUser() {
  const queryClient = useQueryClient();
  
  return useMutation<User, Error, CreateUserDto>(
    newUser => fetch('/api/users', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(newUser),
    }).then(res => res.json()),
    {
      onMutate: async (newUser) => {
        // Cancel outgoing queries
        await queryClient.cancelQueries(['users']);
        
        // Snapshot previous value
        const previousUsers = queryClient.getQueryData<User[]>(['users']);
        
        // Optimistically update
        queryClient.setQueryData<User[]>(['users'], old => [
          ...(old || []),
          { id: Date.now(), ...newUser }
        ]);
        
        return { previousUsers };
      },
      onError: (err, newUser, context) => {
        // Rollback on error
        queryClient.setQueryData(['users'], context?.previousUsers);
      },
      onSettled: () => {
        // Refetch to ensure consistency
        queryClient.invalidateQueries(['users']);
      },
    }
  );
}

🚫 Never mutate the cache directly without rolling back on error—always use onMutate and return context for proper error handling.

Query Invalidation and Manual Cache Updates

TanStack Query provides several methods to update the cache directly or mark queries as stale. Understanding when to use invalidateQueries vs setQueryData is crucial for optimal performance.

TypeScript

import { useQueryClient } from '@tanstack/react-query';
function useUpdateUser() {
  const queryClient = useQueryClient();
  
  const mutation = useMutation<User, Error, Partial<User>>(updateUser, {
    onSuccess: (updatedUser, variables) => {
      // Option 1: Invalidate (triggers refetch)
      queryClient.invalidateQueries(['users']);
      
      // Option 2: Directly update cache
      queryClient.setQueryData(['users', updatedUser.id], updatedUser);
      queryClient.setQueryData<User[]>(['users'], old =>
        old?.map(u => u.id === updatedUser.id ? updatedUser : u) || []
      );
      
      // Option 3: Update specific query
      queryClient.refetchQueries(['users', updatedUser.id]);
    },
  });
  
  return mutation;
}
// Manual cache updates outside components
queryClient.setQueryData(['users', userId], newUser);
queryClient.prefetchQuery(['users', userId], fetchUser);
queryClient.removeQueries(['users', userId]);

💡 Use setQueryData for immediate UI updates and invalidateQueries for ensuring data consistency—combine both for optimistic updates with eventual consistency.

Infinite Queries for Pagination

Infinite queries handle paginated data with cursor-based or offset-based pagination. The useInfiniteQuery hook provides fetchNextPage and fetchPreviousPage functions.

TypeScript

import { useInfiniteQuery } from '@tanstack/react-query';
interface PaginatedResponse<T> {
  data: T[];
  nextCursor?: string;
  hasNext: boolean;
}
function useInfinitePosts() {
  return useInfiniteQuery<Post[], Error>(
    ['posts'],
    async ({ pageParam = null }) => {
      const url = pageParam 
        ? `/api/posts?cursor=${pageParam}`
        : '/api/posts';
      const res = await fetch(url);
      return res.json();
    },
    {
      getNextPageParam: (lastPage) => lastPage.nextCursor,
      getPreviousPageParam: (firstPage) => firstPage.prevCursor,
    }
  );
}
// Flatten pages for rendering
function PostsList() {
  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfinitePosts();
  
  const allPosts = data?.pages.flatMap(page => page.data) || [];
  
  return (
    <div>
      {allPosts.map(post => <PostCard key={post.id} post={post} />)}
      <button 
        onClick={() => fetchNextPage()} 
        disabled={!hasNextPage || isFetchingNextPage}
      >
        {isFetchingNextPage ? 'Loading...' : 'Load More'}
      </button>
    </div>
  );
}

⚠️ When flattening infinite query pages, use structural sharing in select to prevent unnecessary re-renders—memoize the flattened array.

Prefetching and SSR

Server-side rendering requires prefetching queries and hydrating the client cache. TanStack Query provides dehydrate and hydrate utilities for seamless SSR integration.

TypeScript

// Next.js pages router example
import { GetServerSideProps } from 'next';
import { dehydrate, QueryClient } from '@tanstack/react-query';
import { Hydrate, DehydratedState } from '@tanstack/react-query';
export const getServerSideProps: GetServerSideProps = async () => {
  const queryClient = new QueryClient();
  
  // Prefetch queries on server
  await queryClient.prefetchQuery(['users'], fetchUsers);
  await queryClient.prefetchQuery(['posts'], fetchPosts);
  
  return {
    props: {
      dehydratedState: dehydrate(queryClient),
    },
  };
};
function Page({ dehydratedState }: { dehydratedState: DehydratedState }) {
  return (
    <Hydrate state={dehydratedState}>
      <UsersPage />
    </Hydrate>
  );
}
// App router (Next.js 13+) with HydrationBoundary
import { HydrationBoundary } from '@tanstack/react-query';
export default async function Page() {
  const queryClient = new QueryClient();
  await queryClient.prefetchQuery(['users'], fetchUsers);
  
  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <UsersClient />
    </HydrationBoundary>
  );
}

📌 Use HydrationBoundary instead of the deprecated Hydrate component in new projects—both work but HydrationBoundary is the recommended approach.

Advanced Patterns

Advanced patterns include query cancellation with AbortSignal, polling with refetchInterval, and suspense mode for concurrent features.

TypeScript

// Polling with refetchInterval
function usePollingData() {
  return useQuery(['realtime-stats'], fetchStats, {
    refetchInterval: 5000, // Poll every 5 seconds
    refetchIntervalInBackground: false, // Pause when tab is hidden
  });
}
// Query cancellation with AbortSignal
async function searchMovies(query: string, signal: AbortSignal) {
  const response = await fetch(`/api/search?q=${query}`, { signal });
  return response.json();
}
function useSearch(query: string) {
  return useQuery(['search', query], ({ signal }) => searchMovies(query, signal), {
    enabled: !!query, // Only run if query exists
    keepPreviousData: true, // Keep showing old results while new fetch
  });
}
// Suspense mode
function SuspenseComponent() {
  const { data } = useQuery(['users'], fetchUsers, {
    suspense: true, // Throws promise while loading
  });
  
  return <div>{data.map(user => <div key={user.id}>{user.name}</div>)}</div>;
}
// Wrap with Suspense boundary
<Suspense fallback={<div>Loading...</div>}>
  <SuspenseComponent />
</Suspense>

💡 Use keepPreviousData to prevent UI flashes during search queries—users see stale data while new results load.

Performance Optimization

Optimizing TanStack Query involves tuning staleTime and gcTime, leveraging structural sharing, and avoiding unnecessary re-renders through proper query key design.

Option	Purpose	Recommended Value
staleTime	Time before data is considered stale	5-10 minutes for static data
gcTime	Time before inactive data is garbage collected	10-30 minutes
refetchOnWindowFocus	Refetch when window regains focus	true for critical data
refetchOnMount	Refetch on component mount if stale	false for better UX

TypeScript

// Performance optimized query
function useOptimizedQuery(id: number) {
  return useQuery<User, Error>({
    queryKey: ['users', id],
    queryFn: () => fetchUser(id),
    staleTime: 1000 * 60 * 5, // 5 minutes
    gcTime: 1000 * 60 * 10, // 10 minutes
    structuralSharing: (oldData, newData) => {
      // Custom structural sharing for complex objects
      if (oldData && 'id' in oldData && oldData.id === newData.id) {
        return oldData; // Prevent re-renders if data is structurally same
      }
      return newData;
    },
    select: (data) => data, // Transform once, cached transformed result
  });
}
// Memoized derived data
const useUserDisplayName = (userId: number) => {
  const { data } = useUser(userId);
  return useMemo(() => 
    data ? `${data.name} (${data.email})` : null,
    [data?.name, data?.email]
  );
}

🎯 Set longer staleTime for data that doesn't change frequently—reduces network requests and improves perceived performance.

DevTools for Development

TanStack Query Devtools provides a visual interface for inspecting cache state, query status, and triggering manual refetches. Essential for debugging cache behavior.

TypeScript

import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <YourApp />
      {/* Development only - remove in production */}      <ReactQueryDevtools 
        initialIsOpen={false}
        position='bottom-right'
        panelPosition='right'
      />
    </QueryClientProvider>
  );
}
// Custom devtools configuration
<ReactQueryDevtools 
  buttonPosition='top-left'
  copyButtonPosition='bottom-right'
  errorTypes={['FetchError', 'ServerError']}
  styleNonce='dev-tools'
/>

📌 Always conditionally render Devtools in development only—wrap with process.env.NODE_ENV === 'development' check.

Real-World CRUD Example

Here's a complete CRUD implementation with TypeScript, demonstrating proper cache management and optimistic updates for a seamless user experience.

TypeScript

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

interface Todo { id: number; title: string; completed: boolean; }
// Fetch all todos
function useTodos() {
  return useQuery<Todo[], Error>(['todos'], fetchTodos);
}
// Create todo with optimistic update
function useCreateTodo() {
  const queryClient = useQueryClient();
  
  return useMutation<Todo, Error, string>(
    title => createTodo({ title }),
    {
      onMutate: async (title) => {
        await queryClient.cancelQueries(['todos']);
        const previous = queryClient.getQueryData<Todo[]>(['todos']);
        queryClient.setQueryData<Todo[]>(['todos'], old => [
          ...(old || []),
          { id: Date.now(), title, completed: false }
        ]);
        return { previous };
      },
      onError: (err, title, context) => {
        queryClient.setQueryData(['todos'], context?.previous);
      },
      onSettled: () => {
        queryClient.invalidateQueries(['todos']);
      },
    }
  );
}
// Update todo
function useUpdateTodo() {
  const queryClient = useQueryClient();
  
  return useMutation<Todo, Error, Partial<Todo> & { id: number }>(
    updateTodo,
    {
      onMutate: async (updatedTodo) => {
        await queryClient.cancelQueries(['todos']);
        const previous = queryClient.getQueryData<Todo[]>(['todos']);
        queryClient.setQueryData<Todo[]>(['todos'], old =>
          old?.map(todo =>
            todo.id === updatedTodo.id ? { ...todo, ...updatedTodo } : todo
          ) || []
        );
        return { previous };
      },
      onError: (err, variables, context) => {
        queryClient.setQueryData(['todos'], context?.previous);
      },
      onSettled: () => {
        queryClient.invalidateQueries(['todos']);
      },
    }
  );
}
// Delete todo
function useDeleteTodo() {
  const queryClient = useQueryClient();
  
  return useMutation<void, Error, number>(
    deleteTodo,
    {
      onMutate: async (id) => {
        await queryClient.cancelQueries(['todos']);
        const previous = queryClient.getQueryData<Todo[]>(['todos']);
        queryClient.setQueryData<Todo[]>(['todos'], old =>
          old?.filter(todo => todo.id !== id) || []
        );
        return { previous };
      },
      onError: (err, id, context) => {
        queryClient.setQueryData(['todos'], context?.previous);
      },
      onSettled: () => {
        queryClient.invalidateQueries(['todos']);
      },
    }
  );
}
// Complete component
function TodoApp() {
  const { data: todos, isLoading } = useTodos();
  const createTodo = useCreateTodo();
  const updateTodo = useUpdateTodo();
  const deleteTodo = useDeleteTodo();
  
  if (isLoading) return <div>Loading...</div>;
  
  return (
    <div>
      <form onSubmit={(e) => {
        e.preventDefault();
        const input = (e.target as HTMLFormElement).elements.namedItem('title') as HTMLInputElement;
        createTodo.mutate(input.value);
        input.value = '';
      }}>
        <input name="title" placeholder="New todo" />
      </form>
      {todos?.map(todo => (
        <div key={todo.id}>
          <input
            type="checkbox"
            checked={todo.completed}
            onChange={(e) => updateTodo.mutate({ id: todo.id, completed: e.target.checked })}
          />
          {todo.title}
          <button onClick={() => deleteTodo.mutate(todo.id)}>Delete</button>
        </div>
      ))}
    </div>
  );
}

💡 The CRUD pattern shown uses consistent optimistic update logic—extract this into a custom hook for reuse across entities.

Conclusion

TanStack Query transforms how we manage server state in React applications. By embracing the asynchronous nature of server data and providing intelligent caching, background updates, and optimistic mutations, it eliminates entire categories of bugs and boilerplate. Master these patterns and your React applications will have faster, more reliable data fetching with significantly less code.

#programming #web-development #tanstack

Bereket Alemayehu

May 11, 20269 min read0

Reactions

Comments

200w limit

Join the conversation

Account created automatically on first sign-in.