Supercharge Your React Apps with ‘React-Query’: A Beginner’s Guide

Written by

learnmodernjavascript

in

In the world of React, managing data fetching and state can often feel like wrestling an octopus. From making API calls to handling loading states, error handling, and caching, the complexities can quickly bog down your development process. This is where React Query steps in – a powerful and flexible library that simplifies data fetching in your React applications, making your code cleaner, more maintainable, and significantly more efficient. This guide will walk you through the fundamentals of React Query, providing you with practical examples and insights to supercharge your React development workflow.

Why React Query Matters

Before diving into the code, let’s understand why React Query is a game-changer. Traditionally, when fetching data in React, you might use the useState and useEffect hooks to manage loading states, store the data, and handle errors. This approach, while functional, can lead to:

  • Complex Component Logic: Data fetching logic often clutters your components, making them harder to read and maintain.
  • Duplication: Repeating similar data fetching patterns across multiple components.
  • Manual Caching: Implementing caching mechanisms to avoid unnecessary API calls requires extra effort.
  • Inefficient Performance: Without proper caching, your application might make redundant requests, impacting performance.

React Query addresses these issues by providing a streamlined approach to data fetching, including built-in caching, automatic background updates, and optimistic updates. This means you get a more performant and responsive application with less code.

Getting Started with React Query

Let’s get our hands dirty. First, you’ll need to install React Query in your project. Open your terminal and run the following command:

npm install @tanstack/react-query

After the installation is complete, you’ll need to wrap your application with the QueryClientProvider. This provider makes the React Query client available to all your components. Here’s how you do it in your index.js or App.js file:

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

// Create a client
const queryClient = new QueryClient()

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  
    
      
    
  
);

In this example, we create a new QueryClient instance and wrap our App component with QueryClientProvider, passing the client as a prop. This sets up the global configuration for React Query within your application.

Fetching Data with useQuery

The useQuery hook is the heart of React Query. It handles data fetching, caching, and state management. Let’s create a simple component that fetches a list of users from a hypothetical API. 

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

// Function to fetch data from the API
async function fetchUsers() {
  const response = await fetch('https://api.example.com/users');
  if (!response.ok) {
    throw new Error('Network response was not ok');
  }
  return response.json();
}

function Users() {
  // Use the useQuery hook
  const { data, isLoading, error } = useQuery('users', fetchUsers);

  if (isLoading) {
    return <div>Loading...</div>;
  }

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

  return (
    <ul>
      {data.map(user => (
        <li>{user.name}</li>
      ))}
    </ul>
  );
}

export default Users;

Let’s break down this code:

  • fetchUsers Function: This asynchronous function fetches data from your API. Replace the example URL with your actual API endpoint. It’s crucial to handle potential errors within this function.
  • useQuery Hook: The useQuery hook takes two main arguments:
  • Key: A unique string that identifies the query (e.g., ‘users’). This key is used for caching and invalidation.
  • Query Function: The function that fetches the data (e.g., fetchUsers).
  • Destructuring: The useQuery hook returns an object with several useful properties:
  • data: The fetched data, if the request is successful.
  • isLoading: A boolean indicating whether the query is in the loading state.
  • error: An error object, if any error occurred during the fetch.

By using useQuery, you’ve removed the need to manage loading states and errors manually. React Query handles these automatically, making your component much cleaner.

Understanding Caching and Refetching

One of the most significant benefits of React Query is its built-in caching mechanism. By default, React Query caches the data fetched by your queries. When a component using the same query key requests data, React Query first checks its cache. If the data is available and hasn’t expired, it returns the cached data immediately, avoiding a new API call.

Cache Time: By default, React Query caches data for five minutes (300 seconds). You can configure the cache time using the cacheTime option when you initialize your QueryClient:

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      cacheTime: 60 * 1000, // Cache for 60 seconds
    },
  },
});

Refetching: React Query automatically refetches data in the background in the following scenarios:

  • Window Focus: When the user returns to the window, React Query refetches the data.
  • Network Reconnect: If the network connection is lost and then restored, React Query attempts to refetch.
  • Stale Time: If the data is older than the configured staleTime (default is 0), React Query refetches it.

You can customize the refetch behavior using the refetchOnWindowFocus and staleTime options. For example, to prevent refetching on window focus and set a stale time of 10 minutes:

const { data, isLoading, error } = useQuery('users', fetchUsers, {
  refetchOnWindowFocus: false,
  staleTime: 10 * 60 * 1000,
});

Handling Mutations with useMutation

React Query isn’t just for fetching data. It also simplifies handling mutations (POST, PUT, DELETE requests) with the useMutation hook. Let’s create a component to add a new user. 

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

// Function to add a new user
async function addUser(newUser) {
  const response = await fetch('https://api.example.com/users', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(newUser),
  });
  if (!response.ok) {
    throw new Error('Network response was not ok');
  }
  return response.json();
}

function AddUser() {
  const [name, setName] = useState('');
  const queryClient = useQueryClient();

  // Use the useMutation hook
  const { mutate, isLoading, error } = useMutation(addUser, {
    onSuccess: () => {
      // Invalidate the 'users' query to refetch the updated data
      queryClient.invalidateQueries('users');
      setName(''); // Clear the input field after successful mutation
    },
  });

  const handleSubmit = (e) => {
    e.preventDefault();
    mutate({ name });
  };

  return (
    
       setName(e.target.value)}
        placeholder="Enter user name"
      />
      <button type="submit" disabled="{isLoading}">
        {isLoading ? 'Adding...' : 'Add User'}
      </button>
      {error && <p>Error: {error.message}</p>}
    
  );
}

export default AddUser;

Let’s break down this code:

  • addUser Function: This asynchronous function makes a POST request to add a new user.
  • useMutation Hook: The useMutation hook takes two main arguments:
  • Mutation Function: The function that performs the mutation (e.g., addUser).
  • Options Object: An object that allows you to configure behavior such as onSuccess, onError, and onSettled.
  • mutate Function: This function triggers the mutation. It takes the arguments required by the mutation function.
  • onSuccess Callback: This callback is executed when the mutation is successful. In this example, we use queryClient.invalidateQueries('users') to invalidate the ‘users’ query, causing React Query to refetch the user list and update the UI with the new user. We also clear the input field.
  • useQueryClient Hook: This hook provides access to the QueryClient instance, which allows you to interact with the query cache.

By using useMutation, you simplify the process of handling mutations, including error handling and updating the UI after a successful mutation.

Advanced Techniques

Optimistic Updates

Optimistic updates provide a more responsive user experience by immediately updating the UI with the changes before the server confirms them. This makes the UI feel faster, but you’ll need to handle potential errors if the server rejects the changes. Here’s how you can implement optimistic updates:

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

async function addUser(newUser) {
  // Simulate a delay for the API call
  await new Promise((resolve) => setTimeout(resolve, 1000));
  const response = await fetch('https://api.example.com/users', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(newUser),
  });
  if (!response.ok) {
    throw new Error('Network response was not ok');
  }
  return response.json();
}

function AddUserOptimistic() {
  const [name, setName] = useState('');
  const queryClient = useQueryClient();

  const { mutate, isLoading, error } = useMutation(addUser, {
    onMutate: async (newUser) => {
      // Cancel any outgoing refetches
      await queryClient.cancelQueries('users');

      // Snapshot the previous value
      const previousUsers = queryClient.getQueryData('users');

      // Optimistically update to the new value
      queryClient.setQueryData('users', (old) => {
        if (!old) return [newUser]; // Handle initial state
        return [...old, { id: Math.random(), name: newUser.name }];
      });

      // Return context for rollback
      return { previousUsers };
    },
    onError: (err, newUser, context) => {
      // Rollback on failure
      queryClient.setQueryData('users', context.previousUsers);
    },
    onSettled: () => {
      // Refetch the users after the mutation is complete
      queryClient.invalidateQueries('users');
    },
  });

  const handleSubmit = (e) => {
    e.preventDefault();
    mutate({ name });
  };

  return (
    
       setName(e.target.value)}
        placeholder="Enter user name"
      />
      <button type="submit" disabled="{isLoading}">
        {isLoading ? 'Adding...' : 'Add User'}
      </button>
      {error && <p>Error: {error.message}</p>}
    
  );
}

export default AddUserOptimistic;

Key points in this example:

  • onMutate: This function runs immediately before the mutation.
  • queryClient.cancelQueries('users'): Cancels any pending refetches to avoid conflicts.
  • queryClient.getQueryData('users'): Saves the current data to allow for rollback.
  • queryClient.setQueryData('users'): Updates the local cache with the optimistic update. Note we’re generating a temporary ID for the new user.
  • onError: If the mutation fails, this function rolls back the UI to the previous state using the saved data.
  • onSettled: This function always runs after the mutation completes (success or failure). We use it to refetch the data to ensure the UI is in sync with the server.

Query Invalidation

We’ve already seen how to invalidate queries using queryClient.invalidateQueries(). This is the most common approach to refetching data after a mutation. However, there are other ways to control the cache:

  • queryClient.refetchQueries(): Refetches queries without invalidating them. This is useful when you want to update data without clearing the cache.
  • queryClient.removeQueries(): Removes queries from the cache. This is useful for clearing out data you no longer need.

Common Mistakes and How to Fix Them

Here are some common mistakes and how to avoid them when using React Query:

  • Not Providing a Unique Query Key: Always provide a unique key for your queries. If you don’t, React Query won’t be able to cache or invalidate your data correctly. For example, if you’re fetching a user by ID, your key might be ['user', userId].
  • Incorrectly Handling Errors: Make sure you handle errors in your fetch functions and in the onError callback of your mutations. Otherwise, your application might not gracefully handle API failures.
  • Over-Fetching Data: Avoid fetching unnecessary data. Use query parameters to filter and paginate your API requests.
  • Forgetting to Invalidate Queries After Mutations: Always invalidate queries after mutations that modify data (e.g., POST, PUT, DELETE). Otherwise, your UI might not reflect the latest data.
  • Misunderstanding Cache Behavior: Pay attention to the default cache time and stale time. Adjust these values based on your application’s needs to optimize performance and data freshness.

Key Takeaways

  • Simplified Data Fetching: React Query simplifies data fetching, caching, and state management in your React applications.
  • Use useQuery for Data Fetching: Use the useQuery hook to fetch data and manage loading states and errors.
  • Use useMutation for Mutations: Use the useMutation hook to handle mutations (POST, PUT, DELETE) and update your UI.
  • Leverage Caching: React Query’s built-in caching mechanism improves performance and reduces unnecessary API calls.
  • Implement Optimistic Updates: Use optimistic updates to provide a more responsive user experience.
  • Invalidate Queries After Mutations: Invalidate queries after mutations to ensure your UI reflects the latest data.

FAQ

  1. How do I handle pagination with React Query?

    You can use query parameters to paginate your API requests and pass the page number to your query function. In your component, you can use the useQuery hook to fetch data for each page and manage the loading state and errors. You might also want to explore the useInfiniteQuery hook for infinite scrolling.

  2. Can I use React Query with server-side rendering (SSR)?

    Yes, React Query can be used with SSR. You’ll need to use the Hydrate component to hydrate the cache on the client-side after the initial render on the server. This ensures that the client-side and server-side caches are synchronized.

  3. How do I debug React Query?

    React Query provides a developer tools extension for Chrome and Firefox. This extension allows you to inspect your queries, view their status, and monitor their cache. You can also use the React DevTools to inspect the components and see the data and state managed by React Query.

  4. What is the difference between staleTime and cacheTime?

    staleTime determines how long a query’s data is considered fresh. If the data is older than the staleTime, React Query will refetch it in the background when the query is used. cacheTime determines how long a query’s data remains in the cache after the last time it was used. After the cacheTime expires, the query data is garbage collected.

React Query is a powerful library that can significantly improve your React development workflow. By simplifying data fetching, caching, and state management, you can build more performant, maintainable, and user-friendly applications. Implementing these techniques empowers you to create more efficient and responsive user interfaces, leading to a better overall experience for your users. As you continue to build and refine your React applications, you’ll find that embracing these practices not only streamlines your development process but also enhances the robustness and scalability of your projects. The ability to manage data fetching with ease is a cornerstone of modern web development, and React Query provides the tools to do so effectively.

More posts