TanStack Query - The Data Fetching Problem You Didn't Know You Had (Part 2/2)

From Manual Labor to Modern Solutions

In the previous article, we built a “complete” data-fetching component using React’s built-in hooks. The result required three separate state hooks and a complex useEffect just to handle fetching a simple list of to-dos with proper loading and error states.

While functional, our solution suffered from fundamental problems:

  • Excessive boilerplate code
  • No caching mechanism
  • Race condition vulnerabilities
  • Missing production features like retries and background updates

Today, we’re replacing that manual approach with TanStack Query—a purpose-built library for server state management. You’ll see how professional applications handle data fetching and why specialized tools consistently outperform hand-rolled solutions.

Let’s transform our fragile component into something production-ready.

Understanding Server State vs. Client State

Before diving into implementation, you need to understand why TanStack Query exists. It’s not just a fancy fetch wrapper—it’s a server-state management library that solves a specific category of problems.

Client State is data your application owns completely:

  • Is a modal open or closed?
  • What’s the current input field value?
  • Which tab is currently active?

This state is synchronous, predictable, and always current. useState is perfect for client state because your component has complete control over it.

Server State operates under different rules:

  • Data lives on a remote server you don’t control
  • It’s fetched asynchronously with potential for failure
  • It can become stale the moment after you fetch it (other users might update it)
  • Multiple components might need the same data
  • It requires caching, synchronization, and error recovery strategies

The key insight: Using useState to manage server state is like using a screwdriver as a hammer. You can force it to work, but you’re using the wrong tool for the job.

TanStack Query is purpose-built for server state challenges. It provides the specialized features that hand-rolled solutions always seem to be missing.

Step 1: Installation and Setup

First, install the library:

npm install @tanstack/react-query

TanStack Query requires two core pieces in your application:

QueryClient: The central cache manager that stores server data and coordinates all query logic. Think of it as the intelligent memory system for your application’s server state.

QueryClientProvider: A React Context Provider that makes the QueryClient available throughout your component tree. This follows React’s standard pattern for sharing data across components.

Let’s wire it up. Go to your app’s entry point (main.tsx in a Vite app).

main.tsx:

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App.tsx";
import "./index.css";
// 1. Import the necessary stuff
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

// 2. Create a client
const queryClient = new QueryClient();

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    {/* 3. Wrap your App with the provider */}
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  </React.StrictMode>
);

That’s it. Your application now has access to TanStack Query’s server state management capabilities. Every component within the provider can use TanStack Query’s hooks.

Step 2: The Refactor

Let’s review our manual implementation one final time:

TodosComponent (Manual Implementation):

function TodosComponent() {
  const [todos, setTodos] = useState<Todo[]>([]);
  const [isLoading, setIsLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    setIsLoading(true);
    setError(null);
    const fetchTodos = async () => {
      try {
        const response = await fetch(
          "https://jsonplaceholder.typicode.com/todos"
        );
        if (!response.ok) throw new Error(`Server error: ${response.status}`);
        const data = await response.json();
        setTodos(data);
      } catch (e) {
        setError(e as Error);
      } finally {
        setIsLoading(false);
      }
    };
    fetchTodos();
  }, []);

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  // ... render logic ...
}

Now we’ll replace all that complexity with TanStack Query. The core hook is useQuery, which requires two essential properties:

  • queryKey: A unique identifier array for your data. This enables intelligent caching and data synchronization across components.
  • queryFn: The asynchronous function that fetches and returns your data.

Here’s the transformation:

TodosComponent (TanStack Query Implementation):

import { useQuery } from "@tanstack/react-query";

interface Todo {
  userId: number;
  id: number;
  title: string;
  completed: boolean;
}

// This function can even live outside your component! It's just a function.
const fetchTodos = async (): Promise<Todo[]> => {
  const response = await fetch("https://jsonplaceholder.typicode.com/todos");
  if (!response.ok) {
    throw new Error("Network response was not ok");
  }
  return response.json();
};

function TodosComponent() {
  // All our previous useState and useEffect logic is replaced by this one hook.
  const { data, error, status } = useQuery({
    queryKey: ["todos"], // A unique key for this query
    queryFn: fetchTodos, // The function that will fetch the data
  });

  // `status` can be 'pending', 'error', or 'success'
  if (status === "pending") {
    return <span>Loading...</span>;
  }

  if (status === "error") {
    return <span>Error: {error.message}</span>;
  }

  // `status === 'success'`, so `data` is available
  return (
    <ul>
      {data.map((todo) => (
        <li key={todo.id}>{todo.title}</li>
      ))}
    </ul>
  );
}

The transformation is remarkable:

  • Three useState hooks → eliminated
  • Complex useEffect with manual error handling → eliminated
  • Manual loading state management → eliminated
  • Race condition vulnerabilities → eliminated

All replaced by a single, declarative hook that clearly expresses its intent: “This component needs the data identified by ['todos'], fetched using this function.”

The useQuery hook returns a comprehensive object containing:

  • data: The fetched data (typed automatically with TypeScript)
  • error: Any errors that occurred during fetching
  • status: A convenient flag (pending, error, success) for conditional rendering
  • Plus many additional properties for advanced use cases

Understanding Query Keys: The Foundation of Smart Caching

Before diving into mutations, let’s explore query keys more deeply. They’re not just identifiers—they’re the foundation of TanStack Query’s intelligent caching system.

Query keys are hierarchical and semantic:

// Bad: generic, hard to invalidate selectively
const { data } = useQuery({ queryKey: ["data"], queryFn: fetchTodos });

// Good: specific and hierarchical
const { data } = useQuery({ queryKey: ["todos"], queryFn: fetchTodos });
const { data: user } = useQuery({
  queryKey: ["users", userId],
  queryFn: () => fetchUser(userId),
});
const { data: posts } = useQuery({
  queryKey: ["users", userId, "posts"],
  queryFn: () => fetchUserPosts(userId),
});

Why hierarchy matters:

// Invalidate all user-related data
queryClient.invalidateQueries({ queryKey: ["users"] });

// Invalidate only specific user's data
queryClient.invalidateQueries({ queryKey: ["users", userId] });

// Invalidate only specific user's posts
queryClient.invalidateQueries({ queryKey: ["users", userId, "posts"] });

Best practices for query keys:

  • Use descriptive arrays: ['todos', 'completed'] not ['data1']
  • Include dependencies: ['posts', { userId, status }] for filtered data
  • Be consistent across your application
  • Think about invalidation patterns when designing the hierarchy

This hierarchical structure enables precise cache management and is essential for maintaining data consistency in complex applications.

Handling Data Mutations

Reading data is only half the story. Production applications need to create, update, and delete server data. useQuery is specifically designed for read operations (GET requests) that don’t modify server state.

For write operations (POST, PUT, DELETE), TanStack Query provides useMutation. This hook handles the complexities of modifying server data and keeping your cache synchronized.

Let’s add the ability to create new to-dos.

First, we need a function that performs the POST

// This function takes the new to-do's title and sends it to the server.
const addTodo = async (newTodoTitle: string): Promise<Todo> => {
  const response = await fetch("https://jsonplaceholder.typicode.com/todos", {
    method: "POST",
    body: JSON.stringify({
      title: newTodoTitle,
      userId: 1, // Hardcoding for the example
      completed: false,
    }),
    headers: {
      "Content-type": "application/json; charset=UTF-8",
    },
  });

  if (!response.ok) {
    throw new Error("Failed to create new todo");
  }

  return response.json();
};

Now we’ll integrate this with useMutation in our component.

The synchronization challenge: After successfully creating a new to-do, our cached ['todos'] data becomes stale—it doesn’t include the newly created item. We need a way to tell the cache: “This data is no longer accurate. Fetch the latest version.”

This is query invalidation—the mechanism that keeps your cache synchronized after mutations. It’s the crucial bridge between data modifications and cache updates.

Here’s how we do it:

TodosComponent (With Mutation and Invalidation):

import { useState } from "react";
// 1. Import the hooks we need
import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";

// ... (keep the Todo interface and fetchTodos function)
// ... (keep the addTodo async function)

function TodosComponent() {
  const [newTodo, setNewTodo] = useState("");
  // 2. Get a reference to the QueryClient
  const queryClient = useQueryClient();

  // The Query for fetching todos
  const { data, error, status } = useQuery({
    queryKey: ["todos"],
    queryFn: fetchTodos,
  });

  // 3. The Mutation for adding a new todo
  const addTodoMutation = useMutation({
    mutationFn: addTodo, // The function to call
    // 4. This is the magic part
    onSuccess: () => {
      // When the mutation is successful, invalidate the 'todos' query.
      // This will cause `useQuery` to automatically refetch the data.
      queryClient.invalidateQueries({ queryKey: ["todos"] });
    },
  });

  const handleAddTodo = (e: React.FormEvent) => {
    e.preventDefault();
    // 5. Call the `mutate` function with the new todo's title
    addTodoMutation.mutate(newTodo);
    setNewTodo("");
  };

  // ... (keep the loading and error rendering from before) ...
  if (status === "pending") {
    /* ... */
  }
  if (status === "error") {
    /* ... */
  }

  return (
    <div>
      <form onSubmit={handleAddTodo}>
        <input
          type="text"
          value={newTodo}
          onChange={(e) => setNewTodo(e.target.value)}
          placeholder="Add a new todo"
        />
        <button type="submit" disabled={addTodoMutation.isPending}>
          {addTodoMutation.isPending ? "Adding..." : "Add Todo"}
        </button>
      </form>
      {/* You can even show mutation-specific errors */}
      {addTodoMutation.isError && (
        <p style={{ color: "red" }}>
          Error:{" "}
          {addTodoMutation.error instanceof Error
            ? addTodoMutation.error.message
            : "Unknown error"}
        </p>
      )}

      <ul>
        {data.map((todo) => (
          <li key={todo.id}>{todo.title}</li>
        ))}
      </ul>
    </div>
  );
}

Here’s how the mutation system works:

  1. Get QueryClient access: useQueryClient provides access to the central cache manager
  2. Define the mutation: useMutation wraps our addTodo function with loading states and error handling
  3. Handle success: The onSuccess callback executes only after successful mutations
  4. Invalidate cache: queryClient.invalidateQueries({ queryKey: ['todos'] }) marks the todos data as stale
  5. Automatic refetch: Because the ['todos'] query is actively displayed and now marked stale, TanStack Query automatically refetches the fresh data

The user experience: Click “Add” → mutation executes → success triggers cache invalidation → list automatically updates with new data. No manual state management required.

You didn’t write any code to manually refetch data or update local state. You simply declared when the cache should be invalidated, and TanStack Query handled the synchronization automatically.

Built-In Production Features

The code reduction is just the beginning. TanStack Query provides sophisticated features that would take weeks to implement manually:

1. Intelligent Caching

Manual useEffect implementations re-fetch data every time a component mounts, showing loading states for data you already have. TanStack Query eliminates this inefficiency.

How it works:

  • First mount: Fetch data and store in cache under the ['todos'] key
  • Subsequent mounts: Instantly serve cached data while optionally refetching in the background
  • Users see content immediately—no unnecessary loading states

2. Stale-While-Revalidate Pattern

“What if cached data is outdated?” TanStack Query implements a sophisticated freshness strategy.

When serving data from cache, it simultaneously triggers a background refetch. If new data arrives, the UI updates seamlessly. This provides:

  • Immediate response from cache (perceived performance)
  • Eventually consistent data from background refetch (accuracy)
  • Zero configuration required (it’s the default behavior)

This pattern, called “stale-while-revalidate,” is considered the gold standard for data synchronization in modern web applications.

3. Smart Refetch Triggers

TanStack Query automatically refetches data during common scenarios where freshness matters:

  • Window focus: User returns to your app tab
  • Network reconnection: Connection restored after being offline
  • Component remount: Component mounts with potentially stale cache data

These triggers ensure users see current data without manual refresh actions. The system assumes that context changes (like returning to the app) often correlate with a desire for fresh information.

Essential Development Tools

Understanding your application’s server state behavior is crucial for debugging and optimization. TanStack Query provides comprehensive devtools that give you complete visibility into your cache operations.

Install the devtools package:

npm install @tanstack/react-query-devtools

Add the devtools to your application (typically in your root App component):

App.tsx:

import "./App.css";
import { ReactQueryDevtools } from "@tanstack/react-query-devtools";

function App() {
  return (
    <div className="container">
      <h1>My Useless To-Do List</h1>
      <TodosComponent />
      {/* Add the devtools here! */}
      <ReactQueryDevtools initialIsOpen={false} />
    </div>
  );
}
// ...

The devtools provide a small icon in your application’s corner. Clicking it reveals a comprehensive dashboard showing:

  • All query keys in your cache
  • Current status of each query (fresh, fetching, stale, error)
  • Last updated timestamps for cache entries
  • Actual data stored in the cache
  • Query configuration and settings
  • Network request timeline and performance metrics

These tools are invaluable for understanding cache behavior, debugging synchronization issues, and optimizing data fetching strategies in complex applications.

The Professional Development Advantage

By adopting TanStack Query, you’ve transformed a brittle, verbose data-fetching component into a robust, efficient system with significantly less code. More importantly, you’ve gained:

Technical Benefits:

  • Intelligent caching with configurable strategies
  • Automatic background synchronization
  • Built-in error recovery and retry logic
  • Race condition prevention
  • Request deduplication
  • Loading and error state management

Development Benefits:

  • Reduced boilerplate across your entire application
  • Consistent patterns for all server state operations
  • Comprehensive debugging tools
  • Active community and excellent documentation
  • TypeScript support with intelligent type inference

Business Benefits:

  • Improved user experience through faster perceived performance
  • Reduced server load through intelligent caching
  • Lower maintenance costs due to fewer custom implementations
  • Faster feature development with established patterns

What’s Next in Your TanStack Query Journey

This introduction covers the fundamentals, but TanStack Query offers much more:

  • Advanced caching strategies with custom stale times and cache invalidation
  • Optimistic updates for immediate UI feedback
  • Infinite queries for pagination and progressive loading
  • Parallel and dependent queries for complex data relationships
  • Offline support with background sync when connectivity returns
  • Integration patterns with React Router, Next.js, and other frameworks

Key Takeaways

Professional React applications require professional tools for server state management. Hand-rolled useEffect solutions work for simple cases but become liabilities as applications scale.

TanStack Query represents years of accumulated wisdom about data fetching challenges in production applications. By adopting it, you’re not just reducing code—you’re adopting battle-tested patterns that handle edge cases you haven’t even considered yet.

The investment in learning TanStack Query pays dividends throughout your entire React development career. Every future project will benefit from understanding how to properly manage server state.

See you in the next article, where we’ll dive deeper into advanced TanStack Query patterns.