🔄 Lesson 8.4: React Query (TanStack Query)

🤔 Understanding Server State vs Client State

Here's a problem almost every React developer runs into: you fetch some data from an API, drop it in useState, and everything seems fine — until you realize you now have to babysit that data. Is it still fresh? Did another component already fetch it? What happens when the user switches tabs and comes back? React Query (now TanStack Query) exists because managing server state is a fundamentally different problem from managing client state, yet for years we reached for the same useState/useEffect hammer for both. Once you see the distinction, you can't unsee it — and your data-fetching code gets dramatically simpler.

What is Server State?

Server State vs Client State

The Problem with Traditional Approaches

Before React Query, managing server state typically looked like this:

// ❌ The old way - so much boilerplate!
function UserList() {
  const [users, setUsers] = useState<User[]>([]);
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);
  
  useEffect(() => {
    setIsLoading(true);
    setError(null);
    
    fetch('/api/users')
      .then(res => res.json())
      .then(data => {
        setUsers(data);
        setIsLoading(false);
      })
      .catch(err => {
        setError(err.message);
        setIsLoading(false);
      });
  }, []); // When should we refetch?
  
  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;
  
  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

How React Query Solves These Problems

With React Query, the same component becomes:

// ✅ The React Query way - simple and powerful!
import { useQuery } from '@tanstack/react-query';

function UserList() {
  const { data: users, isLoading, error } = useQuery({
    queryKey: ['users'],
    queryFn: () => fetch('/api/users').then(res => res.json())
  });
  
  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  
  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

When to Use React Query

Use React Query for:

• ✅ Fetching data from REST APIs
• ✅ GraphQL queries (with plugins)
• ✅ Data that can become stale
• ✅ Data shared across components
• ✅ CRUD operations
• ✅ Pagination and infinite scroll

Don't use React Query for:

• ❌ Local UI state (modals, themes, forms)
• ❌ One-time configuration fetches
• ❌ Data you don't need to cache
• ❌ Simple, infrequent API calls

⚙️ Installation and Setup

Let's get React Query set up in your React TypeScript project.

Installing React Query

# Install React Query v5 (TanStack Query)
npm install @tanstack/react-query

# Optional: Install DevTools for debugging
npm install @tanstack/react-query-devtools

Setting Up QueryClient

Create and configure a QueryClient with default options:

// src/lib/queryClient.ts

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

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5,  // 5 minutes
      gcTime: 1000 * 60 * 10,    // 10 minutes (v5 renamed cacheTime -> gcTime)
      refetchOnWindowFocus: true,
      refetchOnReconnect: true,
      retry: 1,
    },
  },
});

// Explanation:
// - staleTime: How long until data is considered stale
// - gcTime:    How long to keep UNUSED data in cache before garbage collection
// - refetchOnWindowFocus: Refetch when user returns to the window
// - refetchOnReconnect:   Refetch when the internet reconnects
// - retry:     Number of retry attempts on failure

Wrapping Your App

Provide the QueryClient to your entire application:

// src/main.tsx (or App.tsx)

import React from 'react';
import ReactDOM from 'react-dom/client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import App from './App';

// Create a client
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5, // 5 minutes
      retry: 1,
    },
  },
});

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <QueryClientProvider client={queryClient}>
      <App />
      
      {/* DevTools - only appears in development */}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  </React.StrictMode>
);

Project Structure

Organize your React Query code:

src/
  lib/
    queryClient.ts          // QueryClient configuration
    
  api/
    users.ts               // User-related API functions
    posts.ts               // Post-related API functions
    
  hooks/
    queries/
      useUsers.ts          // User query hooks
      usePosts.ts          // Post query hooks
    mutations/
      useCreateUser.ts     // User mutation hooks
      useUpdatePost.ts     // Post mutation hooks
      
  components/
    users/
      UserList.tsx         // Uses user queries
      CreateUserForm.tsx   // Uses user mutations

Creating API Functions

Separate your API logic from components:

// src/api/users.ts

export interface User {
  id: string;
  name: string;
  email: string;
}

// GET all users
export async function getUsers(): Promise<User[]> {
  const response = await fetch('https://api.example.com/users');
  
  if (!response.ok) {
    throw new Error('Failed to fetch users');
  }
  
  return response.json();
}

// GET single user
export async function getUser(id: string): Promise<User> {
  const response = await fetch(`https://api.example.com/users/${id}`);
  
  if (!response.ok) {
    throw new Error('Failed to fetch user');
  }
  
  return response.json();
}

// POST create user
export async function createUser(userData: Omit<User, 'id'>): Promise<User> {
  const response = await fetch('https://api.example.com/users', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(userData),
  });
  
  if (!response.ok) {
    throw new Error('Failed to create user');
  }
  
  return response.json();
}

// PATCH update user
export async function updateUser(
  id: string, 
  updates: Partial<User>
): Promise<User> {
  const response = await fetch(`https://api.example.com/users/${id}`, {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(updates),
  });
  
  if (!response.ok) {
    throw new Error('Failed to update user');
  }
  
  return response.json();
}

// DELETE user
export async function deleteUser(id: string): Promise<void> {
  const response = await fetch(`https://api.example.com/users/${id}`, {
    method: 'DELETE',
  });
  
  if (!response.ok) {
    throw new Error('Failed to delete user');
  }
}

📥 Queries: Fetching Data

Queries are the core of React Query. They fetch data, cache it, and keep it synchronized with the server.

Basic useQuery

// src/components/UserList.tsx

import { useQuery } from '@tanstack/react-query';
import { getUsers } from '../api/users';

function UserList() {
  const { data, isLoading, error } = useQuery({
    queryKey: ['users'],
    queryFn: getUsers
  });
  
  if (isLoading) {
    return <div>Loading users...</div>;
  }
  
  if (error) {
    return <div>Error: {error.message}</div>;
  }
  
  return (
    <ul>
      {data?.map(user => (
        <li key={user.id}>
          {user.name} - {user.email}
        </li>
      ))}
    </ul>
  );
}

Understanding Query States

React Query provides detailed state information:

function UserList() {
  const { 
    data,              // The data returned from queryFn
    error,             // Error object if query failed
    isLoading,         // true on first load (no cached data)
    isFetching,        // true whenever fetching (even if cached data exists)
    isError,           // true if query errored
    isSuccess,         // true if query succeeded
    status,            // 'pending' | 'error' | 'success'
    fetchStatus,       // 'fetching' | 'paused' | 'idle'
    refetch,           // Function to manually refetch
  } = useQuery({
    queryKey: ['users'],
    queryFn: getUsers
  });
  
  // Different ways to check loading
  if (isLoading) {
    return <div>Loading for the first time...</div>;
  }
  
  return (
    <div>
      {isFetching && <div>Updating...</div>}
      {/* Render data */}
    </div>
  );
}

Query with Parameters

// src/components/UserProfile.tsx

import { useQuery } from '@tanstack/react-query';
import { getUser } from '../api/users';

function UserProfile({ userId }: { userId: string }) {
  const { data: user, isLoading, error } = useQuery({
    queryKey: ['user', userId], // Include params in key!
    queryFn: () => getUser(userId),
    enabled: !!userId, // Only run if userId exists
  });
  
  if (isLoading) return <div>Loading user...</div>;
  if (error) return <div>Error: {error.message}</div>;
  if (!user) return <div>User not found</div>;
  
  return (
    <div>
      <h2>{user.name}</h2>
      <p>{user.email}</p>
    </div>
  );
}

const { data: user } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => getUser(userId),
  enabled: !!userId && hasPermission
});

TypeScript Integration

// Strongly typed query
const { data } = useQuery<User[], Error>({
  queryKey: ['users'],
  queryFn: getUsers
});
// data is typed as User[] | undefined
// error is typed as Error | null

// With type inference (recommended)
const { data, error } = useQuery({
  queryKey: ['users'],
  queryFn: getUsers // Return type inferred as User[]
});
// TypeScript infers types from getUsers function

Query Options

const { data } = useQuery({
  queryKey: ['users'],
  queryFn: getUsers,

  // Caching
  staleTime: 1000 * 60 * 5,           // 5 minutes until stale
  gcTime: 1000 * 60 * 10,             // Keep unused data 10 min (was cacheTime in v4)

  // Refetching
  refetchOnMount: true,               // Refetch on mount if data is stale
  refetchOnWindowFocus: true,         // Refetch when window regains focus
  refetchOnReconnect: true,           // Refetch when internet reconnects
  refetchInterval: false,             // Poll every X ms (or false to disable)
  refetchIntervalInBackground: false, // Poll even when window not focused

  // Retry
  retry: 3,                           // Retry failed requests 3 times
  retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),

  // Other
  enabled: true,                      // Enable/disable the query
  placeholderData: [],                // Show while loading (NOT written to cache)
  initialData: [],                    // Seed data (IS written to cache),
  select: (data) => data,             // Transform/derive data before it reaches the component
});

Reshaping Data with select

Often a component only needs a slice of the response, or wants it transformed. The select option lets you derive exactly what the component needs — and React Query is smart enough to only re-render when the selected value changes, not the whole payload.

// Only re-renders when the COUNT changes, not on every user edit
function UserCount() {
  const { data: count } = useQuery({
    queryKey: ['users'],
    queryFn: getUsers,
    select: (users) => users.length, // derive a number from User[]
  });

  return <p>{count} users online</p>;
}

// Sort or map without touching the cached data
const { data: names } = useQuery({
  queryKey: ['users'],
  queryFn: getUsers,
  select: (users) => users.map(u => u.name).sort(),
});

Suspense-Powered Queries with useSuspenseQuery

React 19 pairs beautifully with Suspense for data fetching. TanStack Query v5 ships a first-class useSuspenseQuery hook. Instead of checking isLoading yourself, you let a parent <Suspense> boundary show the fallback and an <ErrorBoundary> catch failures. The big win for TypeScript: because the hook suspends until data exists, data is never undefined — no more optional chaining everywhere.

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

function UserList() {
  // No isLoading / error branches here — Suspense handles them.
  const { data } = useSuspenseQuery({
    queryKey: ['users'],
    queryFn: getUsers,
  });

  // 'data' is User[], NOT User[] | undefined 🎉
  return (
    <ul>
      {data.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

function Page() {
  return (
    <Suspense fallback={<div>Loading users…</div>}>
      <UserList />
    </Suspense>
  );
}

🔑 Query Keys and Caching

Query keys are the backbone of React Query's caching system. Understanding them is crucial for effective data management.

How Query Keys Work

// Simple string key
useQuery({
  queryKey: ['users'],
  queryFn: getUsers
});

// Array with parameters
useQuery({
  queryKey: ['user', userId],
  queryFn: () => getUser(userId)
});

// Complex keys with multiple parameters
useQuery({
  queryKey: ['users', { status: 'active', page: 1 }],
  queryFn: () => getUsers({ status: 'active', page: 1 })
});

// Keys are compared deeply
['users', { page: 1, status: 'active' }] 
  === 
['users', { status: 'active', page: 1 }]  // true!

Query Key Patterns

// ✅ Good: Hierarchical structure
['users']                          // All users
['users', userId]                  // Specific user
['users', userId, 'posts']         // User's posts
['users', userId, 'posts', postId] // Specific post

// ✅ Good: With filters/params
['users', { status: 'active' }]
['posts', { page: 1, limit: 10 }]
['products', { category: 'electronics', sort: 'price' }]

// ❌ Bad: Inconsistent structure
['users']
['userById', userId]  // Should be ['users', userId]
['getUserPosts', userId]  // Should be ['users', userId, 'posts']

Query Key Factory

Create a centralized key factory for consistency:

// src/lib/queryKeys.ts

export const queryKeys = {
  // Users
  users: {
    all: ['users'] as const,
    lists: () => [...queryKeys.users.all, 'list'] as const,
    list: (filters: string) => 
      [...queryKeys.users.lists(), { filters }] as const,
    details: () => [...queryKeys.users.all, 'detail'] as const,
    detail: (id: string) => 
      [...queryKeys.users.details(), id] as const,
  },
  
  // Posts
  posts: {
    all: ['posts'] as const,
    lists: () => [...queryKeys.posts.all, 'list'] as const,
    list: (filters: string) => 
      [...queryKeys.posts.lists(), { filters }] as const,
    details: () => [...queryKeys.posts.all, 'detail'] as const,
    detail: (id: string) => 
      [...queryKeys.posts.details(), id] as const,
  },
};

// Usage
useQuery({
  queryKey: queryKeys.users.detail(userId),
  queryFn: () => getUser(userId)
});

useQuery({
  queryKey: queryKeys.posts.list('published'),
  queryFn: () => getPosts({ status: 'published' })
});

Understanding the Cache

Stale Time vs Cache Time

useQuery({
  queryKey: ['users'],
  queryFn: getUsers,
  staleTime: 1000 * 60 * 5,  // 5 minutes
  gcTime: 1000 * 60 * 10      // 10 minutes (was cacheTime in v4)
});

// Timeline:
// t=0:  Fetch data, cache it as "fresh"
// t=5m: Data becomes "stale" but still in cache
//       - On mount, return stale data + refetch in background
// t=10m: Data removed from cache (garbage collected)
//       - On mount, show loading + fetch fresh data

That two-timer model is the single most important idea in React Query's cache. It's worth picturing the whole lifecycle of one cache entry from birth to garbage collection:

Notice that fresh vs. stale controls refetching, while active vs. inactive (plus gcTime) controls memory. The two are independent: data can be stale but still cached for ages, or fresh yet about to be garbage-collected the moment the last component using it unmounts.

🔧 Mutations: Updating Data

While queries are for reading data, mutations are for creating, updating, or deleting data. React Query's useMutation hook provides a powerful abstraction for modifying server state with automatic cache updates and optimistic UI patterns.

Basic Mutation Example

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

interface CreateUserData {
  name: string;
  email: string;
}

interface User {
  id: string;
  name: string;
  email: string;
  createdAt: string;
}

// API function
const createUser = async (userData: CreateUserData): Promise<User> => {
  const response = await fetch('/api/users', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(userData)
  });
  
  if (!response.ok) {
    throw new Error('Failed to create user');
  }
  
  return response.json();
};

// Component
function CreateUserForm() {
  const queryClient = useQueryClient();
  
  const mutation = useMutation({
    mutationFn: createUser,
    onSuccess: (data) => {
      // Invalidate and refetch users list
      queryClient.invalidateQueries({ queryKey: ['users'] });
      console.log('User created:', data);
    },
    onError: (error) => {
      console.error('Error creating user:', error);
    }
  });

  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    
    mutation.mutate({
      name: formData.get('name') as string,
      email: formData.get('email') as string
    });
  };

  return (
    <form onSubmit={handleSubmit}>
      <input name="name" placeholder="Name" required />
      <input name="email" type="email" placeholder="Email" required />
      
      <button 
        type="submit" 
        disabled={mutation.isPending}
      >
        {mutation.isPending ? 'Creating...' : 'Create User'}
      </button>
      
      {mutation.isError && (
        <div className="error">
          Error: {mutation.error.message}
        </div>
      )}
      
      {mutation.isSuccess && (
        <div className="success">
          User created successfully!
        </div>
      )}
    </form>
  );
}

Mutation States

const mutation = useMutation({ mutationFn: createUser });

// Access mutation states
mutation.isPending;   // true while request is in flight
mutation.isError;     // true if mutation failed
mutation.isSuccess;   // true if mutation succeeded
mutation.isIdle;      // true if mutation hasn't been called yet

mutation.error;       // Error object if failed
mutation.data;        // Response data if successful
mutation.status;      // 'idle' | 'pending' | 'error' | 'success'

// Call the mutation
mutation.mutate(userData);

// Or use async version with Promise
mutation.mutateAsync(userData)
  .then(data => console.log('Success:', data))
  .catch(error => console.error('Error:', error));

Update and Delete Mutations

// Update mutation
const updateUser = async ({ id, data }: { 
  id: string; 
  data: Partial<User> 
}): Promise<User> => {
  const response = await fetch(`/api/users/${id}`, {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data)
  });
  return response.json();
};

const updateMutation = useMutation({
  mutationFn: updateUser,
  onSuccess: (data, variables) => {
    // Invalidate specific user and list
    queryClient.invalidateQueries({ queryKey: ['users'] });
    queryClient.invalidateQueries({ queryKey: ['users', variables.id] });
  }
});

// Delete mutation
const deleteUser = async (userId: string): Promise<void> => {
  await fetch(`/api/users/${userId}`, {
    method: 'DELETE'
  });
};

const deleteMutation = useMutation({
  mutationFn: deleteUser,
  onSuccess: (_, deletedId) => {
    // Remove from cache
    queryClient.setQueryData<User[]>(['users'], (old) => 
      old?.filter(user => user.id !== deletedId)
    );
  }
});

// Usage
<button onClick={() => updateMutation.mutate({ 
  id: user.id, 
  data: { name: 'New Name' } 
})}>
  Update
</button>

<button onClick={() => deleteMutation.mutate(user.id)}>
  Delete
</button>

Mutation with Variables

// Access mutation variables in callbacks
const mutation = useMutation({
  mutationFn: createUser,
  onMutate: async (variables) => {
    // Called before mutation function
    console.log('About to create:', variables);
    
    // Can return context for rollback
    return { timestamp: Date.now() };
  },
  onSuccess: (data, variables, context) => {
    console.log('Created:', data);
    console.log('With input:', variables);
    console.log('Context:', context);
  },
  onError: (error, variables, context) => {
    console.error('Failed to create:', variables);
    console.log('Rollback context:', context);
  },
  onSettled: (data, error, variables, context) => {
    // Called whether success or error
    console.log('Mutation finished');
  }
});

// All callbacks receive:
// - data: response from mutationFn (success only)
// - error: error object (error only)
// - variables: input passed to mutate()
// - context: value returned from onMutate

🔄 Cache Invalidation and Refetching

One of React Query's superpowers is intelligent cache management. Understanding when and how to invalidate queries ensures your UI always displays the most current data without unnecessary network requests.

Query Invalidation Strategies

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

function MyComponent() {
  const queryClient = useQueryClient();

  // 1. Invalidate exact query
  queryClient.invalidateQueries({ 
    queryKey: ['users', '123'] 
  });

  // 2. Invalidate all queries starting with key
  queryClient.invalidateQueries({ 
    queryKey: ['users'] 
  });
  // Invalidates: ['users'], ['users', '123'], ['users', 'list'], etc.

  // 3. Invalidate with predicate function
  queryClient.invalidateQueries({
    predicate: (query) => {
      return query.queryKey[0] === 'users' && 
             query.state.data !== undefined;
    }
  });

  // 4. Invalidate multiple query keys
  queryClient.invalidateQueries({ queryKey: ['users'] });
  queryClient.invalidateQueries({ queryKey: ['posts'] });

  // 5. Invalidate and refetch immediately
  await queryClient.invalidateQueries({ 
    queryKey: ['users'],
    refetchType: 'active' // 'active' | 'inactive' | 'all' | 'none'
  });
}

Manual Refetching

function UserProfile({ userId }: { userId: string }) {
  const { data, refetch, isRefetching } = useQuery({
    queryKey: ['users', userId],
    queryFn: () => getUser(userId)
  });

  return (
    <div>
      <h2>{data?.name}</h2>
      
      <button 
        onClick={() => refetch()}
        disabled={isRefetching}
      >
        {isRefetching ? 'Refreshing...' : 'Refresh'}
      </button>
    </div>
  );
}

// Refetch from outside component
const queryClient = useQueryClient();

// Refetch specific query
queryClient.refetchQueries({ queryKey: ['users', '123'] });

// Refetch all queries with key prefix
queryClient.refetchQueries({ queryKey: ['users'] });

// Refetch all active queries
queryClient.refetchQueries({ type: 'active' });

Setting Query Data Directly

const queryClient = useQueryClient();

// 1. Set data directly (overwrite)
queryClient.setQueryData<User>(['users', '123'], {
  id: '123',
  name: 'John Doe',
  email: 'john@example.com'
});

// 2. Update data with function (merge)
queryClient.setQueryData<User>(['users', '123'], (oldData) => {
  if (!oldData) return oldData;
  return { ...oldData, name: 'Updated Name' };
});

// 3. Update list after creating item
const createMutation = useMutation({
  mutationFn: createUser,
  onSuccess: (newUser) => {
    // Add new user to cached list
    queryClient.setQueryData<User[]>(['users'], (old) => {
      return old ? [...old, newUser] : [newUser];
    });
  }
});

// 4. Update list after deleting item
const deleteMutation = useMutation({
  mutationFn: deleteUser,
  onSuccess: (_, deletedId) => {
    // Remove user from cached list
    queryClient.setQueryData<User[]>(['users'], (old) => {
      return old?.filter(user => user.id !== deletedId);
    });
  }
});

Removing Queries from Cache

// Remove specific query
queryClient.removeQueries({ queryKey: ['users', '123'] });

// Remove all queries with prefix
queryClient.removeQueries({ queryKey: ['users'] });

// Clear entire cache
queryClient.clear();

// Example: Clear user data on logout
const logout = () => {
  // Clear all user-related queries
  queryClient.removeQueries({ queryKey: ['users'] });
  queryClient.removeQueries({ queryKey: ['profile'] });
  
  // Or clear everything
  queryClient.clear();
  
  // Then navigate to login
  navigate('/login');
};

// ❌ BAD - Invalidates ALL queries
queryClient.invalidateQueries();

// ❌ BAD - Invalidates all user queries after updating one
queryClient.invalidateQueries({ queryKey: ['users'] });

// ✅ GOOD - Only invalidate what changed
queryClient.invalidateQueries({ queryKey: ['users', userId] });

⚡ Optimistic Updates

Optimistic updates make your app feel instant by updating the UI immediately, before waiting for the server response. If the server request fails, React Query automatically rolls back to the previous state.

Basic Optimistic Update

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

const toggleTodo = async (id: string): Promise<Todo> => {
  const response = await fetch(`/api/todos/${id}/toggle`, {
    method: 'PATCH'
  });
  return response.json();
};

function TodoList() {
  const queryClient = useQueryClient();

  const toggleMutation = useMutation({
    mutationFn: toggleTodo,
    
    // Before mutation starts
    onMutate: async (todoId) => {
      // Cancel outgoing refetches (so they don't overwrite optimistic update)
      await queryClient.cancelQueries({ queryKey: ['todos'] });

      // Snapshot the previous value
      const previousTodos = queryClient.getQueryData<Todo[]>(['todos']);

      // Optimistically update the cache
      queryClient.setQueryData<Todo[]>(['todos'], (old) => {
        return old?.map(todo =>
          todo.id === todoId
            ? { ...todo, completed: !todo.completed }
            : todo
        );
      });

      // Return context with snapshot
      return { previousTodos };
    },
    
    // On error, rollback
    onError: (error, variables, context) => {
      queryClient.setQueryData(['todos'], context?.previousTodos);
      alert('Failed to update todo. Please try again.');
    },
    
    // Always refetch after error or success
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: ['todos'] });
    }
  });

  return (
    <ul>
      {todos?.map(todo => (
        <li key={todo.id}>
          <input
            type="checkbox"
            checked={todo.completed}
            onChange={() => toggleMutation.mutate(todo.id)}
          />
          {todo.title}
        </li>
      ))}
    </ul>
  );
}

Optimistic Create

const createTodo = async (newTodo: { title: string }): Promise<Todo> => {
  const response = await fetch('/api/todos', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(newTodo)
  });
  return response.json();
};

const createMutation = useMutation({
  mutationFn: createTodo,
  
  onMutate: async (newTodo) => {
    await queryClient.cancelQueries({ queryKey: ['todos'] });
    
    const previousTodos = queryClient.getQueryData<Todo[]>(['todos']);
    
    // Create optimistic todo with temporary ID
    const optimisticTodo: Todo = {
      id: `temp-${Date.now()}`, // Temporary ID
      title: newTodo.title,
      completed: false
    };
    
    // Add optimistic todo to cache
    queryClient.setQueryData<Todo[]>(['todos'], (old) => {
      return old ? [...old, optimisticTodo] : [optimisticTodo];
    });
    
    return { previousTodos, optimisticTodo };
  },
  
  onSuccess: (newTodo, variables, context) => {
    // Replace temp todo with real one from server
    queryClient.setQueryData<Todo[]>(['todos'], (old) => {
      return old?.map(todo => 
        todo.id === context.optimisticTodo.id ? newTodo : todo
      );
    });
  },
  
  onError: (error, variables, context) => {
    queryClient.setQueryData(['todos'], context?.previousTodos);
  },
  
  onSettled: () => {
    queryClient.invalidateQueries({ queryKey: ['todos'] });
  }
});

Optimistic Delete

const deleteTodo = async (id: string): Promise<void> => {
  await fetch(`/api/todos/${id}`, { method: 'DELETE' });
};

const deleteMutation = useMutation({
  mutationFn: deleteTodo,
  
  onMutate: async (todoId) => {
    await queryClient.cancelQueries({ queryKey: ['todos'] });
    
    const previousTodos = queryClient.getQueryData<Todo[]>(['todos']);
    
    // Remove todo optimistically
    queryClient.setQueryData<Todo[]>(['todos'], (old) => {
      return old?.filter(todo => todo.id !== todoId);
    });
    
    return { previousTodos };
  },
  
  onError: (error, variables, context) => {
    // Restore deleted todo on error
    queryClient.setQueryData(['todos'], context?.previousTodos);
    alert('Failed to delete todo');
  },
  
  onSettled: () => {
    queryClient.invalidateQueries({ queryKey: ['todos'] });
  }
});

Complex Optimistic Update: Like Button

interface Post {
  id: string;
  title: string;
  likes: number;
  likedBy: string[]; // Array of user IDs
}

const toggleLike = async ({ 
  postId, 
  userId 
}: { 
  postId: string; 
  userId: string 
}): Promise<Post> => {
  const response = await fetch(`/api/posts/${postId}/like`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ userId })
  });
  return response.json();
};

function LikeButton({ post, userId }: { post: Post; userId: string }) {
  const queryClient = useQueryClient();
  const isLiked = post.likedBy.includes(userId);

  const likeMutation = useMutation({
    mutationFn: toggleLike,
    
    onMutate: async ({ postId, userId }) => {
      await queryClient.cancelQueries({ queryKey: ['posts', postId] });
      
      const previousPost = queryClient.getQueryData<Post>(['posts', postId]);
      
      queryClient.setQueryData<Post>(['posts', postId], (old) => {
        if (!old) return old;
        
        const isCurrentlyLiked = old.likedBy.includes(userId);
        
        return {
          ...old,
          likes: isCurrentlyLiked ? old.likes - 1 : old.likes + 1,
          likedBy: isCurrentlyLiked
            ? old.likedBy.filter(id => id !== userId)
            : [...old.likedBy, userId]
        };
      });
      
      return { previousPost };
    },
    
    onError: (error, variables, context) => {
      if (context?.previousPost) {
        queryClient.setQueryData(['posts', variables.postId], context.previousPost);
      }
    },
    
    onSettled: (data, error, variables) => {
      queryClient.invalidateQueries({ queryKey: ['posts', variables.postId] });
    }
  });

  return (
    <button
      onClick={() => likeMutation.mutate({ postId: post.id, userId })}
      disabled={likeMutation.isPending}
      style={{
        color: isLiked ? 'red' : 'gray',
        opacity: likeMutation.isPending ? 0.6 : 1
      }}
    >
      ❤️ {post.likes}
    </button>
  );
}

🎯 Best Practices and Patterns

After mastering the basics of React Query, following these best practices will help you build maintainable, performant applications that leverage React Query's full power.

1. Organize API Functions

// api/users.ts
export interface User {
  id: string;
  name: string;
  email: string;
}

export const usersApi = {
  getAll: async (): Promise<User[]> => {
    const response = await fetch('/api/users');
    if (!response.ok) throw new Error('Failed to fetch users');
    return response.json();
  },
  
  getById: async (id: string): Promise<User> => {
    const response = await fetch(`/api/users/${id}`);
    if (!response.ok) throw new Error('Failed to fetch user');
    return response.json();
  },
  
  create: async (data: Omit<User, 'id'>): Promise<User> => {
    const response = await fetch('/api/users', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data)
    });
    if (!response.ok) throw new Error('Failed to create user');
    return response.json();
  },
  
  update: async ({ id, data }: { id: string; data: Partial<User> }): Promise<User> => {
    const response = await fetch(`/api/users/${id}`, {
      method: 'PATCH',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data)
    });
    if (!response.ok) throw new Error('Failed to update user');
    return response.json();
  },
  
  delete: async (id: string): Promise<void> => {
    const response = await fetch(`/api/users/${id}`, { method: 'DELETE' });
    if (!response.ok) throw new Error('Failed to delete user');
  }
};

2. Create Custom Hooks for Queries

// hooks/useUsers.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { usersApi, User } from '../api/users';

// Query keys factory
export const userKeys = {
  all: ['users'] as const,
  lists: () => [...userKeys.all, 'list'] as const,
  list: (filters: string) => [...userKeys.lists(), { filters }] as const,
  details: () => [...userKeys.all, 'detail'] as const,
  detail: (id: string) => [...userKeys.details(), id] as const,
};

// Get all users
export function useUsers() {
  return useQuery({
    queryKey: userKeys.lists(),
    queryFn: usersApi.getAll,
    staleTime: 1000 * 60 * 5, // 5 minutes
  });
}

// Get single user
export function useUser(id: string) {
  return useQuery({
    queryKey: userKeys.detail(id),
    queryFn: () => usersApi.getById(id),
    staleTime: 1000 * 60 * 5,
  });
}

// Create user
export function useCreateUser() {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: usersApi.create,
    onSuccess: (newUser) => {
      // Optimistically add to list
      queryClient.setQueryData<User[]>(userKeys.lists(), (old) => {
        return old ? [...old, newUser] : [newUser];
      });
      // Invalidate to refetch from server
      queryClient.invalidateQueries({ queryKey: userKeys.lists() });
    },
  });
}

// Update user
export function useUpdateUser() {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: usersApi.update,
    onSuccess: (updatedUser) => {
      // Update specific user cache
      queryClient.setQueryData(
        userKeys.detail(updatedUser.id),
        updatedUser
      );
      // Invalidate list
      queryClient.invalidateQueries({ queryKey: userKeys.lists() });
    },
  });
}

// Delete user
export function useDeleteUser() {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: usersApi.delete,
    onSuccess: (_, deletedId) => {
      // Remove from list cache
      queryClient.setQueryData<User[]>(userKeys.lists(), (old) => {
        return old?.filter(user => user.id !== deletedId);
      });
      // Remove detail cache
      queryClient.removeQueries({ queryKey: userKeys.detail(deletedId) });
    },
  });
}

3. Configure Global Defaults

// App.tsx or main provider file
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      // Global defaults for ALL queries
      staleTime: 1000 * 60 * 5,        // 5 minutes
      gcTime: 1000 * 60 * 10,          // 10 minutes (was cacheTime)
      refetchOnWindowFocus: false,     // Don't refetch on tab focus
      refetchOnReconnect: true,        // Refetch on network reconnect
      retry: 1,                        // Retry failed requests once
      retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
    },
    mutations: {
      // Global defaults for ALL mutations
      retry: 0,                        // Don't retry mutations
      onError: (error) => {
        console.error('Mutation error:', error);
        // Show global error toast
      },
    },
  },
});

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <YourApp />
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  );
}

4. Error Handling Patterns

// Create custom error class
class ApiError extends Error {
  constructor(
    message: string,
    public status: number,
    public data?: any
  ) {
    super(message);
    this.name = 'ApiError';
  }
}

// Enhanced fetch with error handling
async function fetchApi<T>(url: string, options?: RequestInit): Promise<T> {
  const response = await fetch(url, options);
  
  if (!response.ok) {
    const errorData = await response.json().catch(() => ({}));
    throw new ApiError(
      errorData.message || 'Request failed',
      response.status,
      errorData
    );
  }
  
  return response.json();
}

// Use in component with proper error typing
function UserProfile({ userId }: { userId: string }) {
  const { data, error, isError } = useQuery({
    queryKey: ['users', userId],
    queryFn: () => fetchApi<User>(`/api/users/${userId}`)
  });

  if (isError) {
    if (error instanceof ApiError) {
      if (error.status === 404) {
        return <div>User not found</div>;
      }
      if (error.status === 403) {
        return <div>Access denied</div>;
      }
    }
    return <div>Error: {error.message}</div>;
  }

  return <div>{data?.name}</div>;
}

5. Prefetching Data

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

function UserList() {
  const queryClient = useQueryClient();
  const { data: users } = useUsers();

  // Prefetch user details on hover
  const prefetchUser = (userId: string) => {
    queryClient.prefetchQuery({
      queryKey: userKeys.detail(userId),
      queryFn: () => usersApi.getById(userId),
      staleTime: 1000 * 60 * 5,
    });
  };

  return (
    <ul>
      {users?.map(user => (
        <li
          key={user.id}
          onMouseEnter={() => prefetchUser(user.id)}
        >
          <Link to={`/users/${user.id}`}>{user.name}</Link>
        </li>
      ))}
    </ul>
  );
}

// Prefetch on route loader
function UserDetailPage() {
  const { userId } = useParams();
  const queryClient = useQueryClient();
  
  useEffect(() => {
    // Prefetch related data
    queryClient.prefetchQuery({
      queryKey: ['posts', userId],
      queryFn: () => getPostsByUser(userId!)
    });
  }, [userId, queryClient]);
  
  const { data } = useUser(userId!);
  
  return <div>{data?.name}</div>;
}

6. Dependent Queries

// Query B depends on data from Query A
function UserPosts({ userId }: { userId: string }) {
  // First query
  const { data: user } = useQuery({
    queryKey: ['users', userId],
    queryFn: () => getUser(userId)
  });

  // Second query depends on first
  const { data: posts } = useQuery({
    queryKey: ['posts', user?.id],
    queryFn: () => getPosts(user!.id),
    enabled: !!user, // Only run when user exists
  });

  return <div>{posts?.length} posts</div>;
}

// Parallel dependent queries
function Dashboard() {
  const { data: user } = useUser();
  
  // These only run when user exists
  const queries = useQueries({
    queries: [
      {
        queryKey: ['posts', user?.id],
        queryFn: () => getPosts(user!.id),
        enabled: !!user,
      },
      {
        queryKey: ['comments', user?.id],
        queryFn: () => getComments(user!.id),
        enabled: !!user,
      },
      {
        queryKey: ['likes', user?.id],
        queryFn: () => getLikes(user!.id),
        enabled: !!user,
      },
    ],
  });

  const [postsQuery, commentsQuery, likesQuery] = queries;

  if (queries.some(q => q.isLoading)) {
    return <div>Loading...</div>;
  }

  return (
    <div>
      <div>Posts: {postsQuery.data?.length}</div>
      <div>Comments: {commentsQuery.data?.length}</div>
      <div>Likes: {likesQuery.data?.length}</div>
    </div>
  );
}