To start using TanStack Query in your React application, you first need to install the package. Open your terminal and run the following command in your project directory:

npm install @tanstack/react-query

After installing, you must set up the QueryClient and wrap your application with the QueryClientProvider component. This enables TanStack Query features throughout your app. Begin by importing the necessary modules in your entry file, such as index.js or App.js:

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

Create an instance of QueryClient:

const queryClient = new QueryClient();

Then, use the QueryClientProvider to wrap your main App component, passing the queryClient instance via the client prop:

const container = document.getElementById("root");
const root = createRoot(container);

root.render(
  <QueryClientProvider client={queryClient}>
    <App />
  </QueryClientProvider>
);

The QueryClient is the core of TanStack Query's data management. It handles all queries, mutations, and caching. You can configure the QueryClient by passing an options object when creating it. Common configuration options include:

• defaultOptions: set default behaviors for queries and mutations;
• queryCache: customize caching strategy for queries;
• mutationCache: customize caching strategy for mutations.

A typical configuration might look like this:

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      retry: 2,
      refetchOnWindowFocus: false,
      staleTime: 1000 * 60 * 5 // 5 minutes
    }
  }
});

This setup tells TanStack Query to retry failed queries twice, not refetch data when the window regains focus, and treat data as fresh for five minutes.

When organizing your project, it is best practice to keep the QueryClient instance and the QueryClientProvider setup at the root level of your app. This ensures that all components can access TanStack Query features. You can create a dedicated file for the client configuration, such as queryClient.js, and import it where you set up the provider. Keeping your query logic in custom hooks or feature-based folders also makes your codebase cleaner and more maintainable.