The TanStack Query ecosystem of tools is a powerful and modern stack that enables developers to build highly functional full-stack applications. The ecosystem is powered by Vinxi, a JavaScript SDK that streamlines full-stack app development with Vite, ensuring deployment across any environment where JavaScript runs. TanStack delivers a top-tier front-end developer experience while also offering robust back-end capabilities, giving you the best of both worlds.

Why Choose TanStack Query?

1. Simplified Server State Management

Unlike global state managers such as Redux or MobX, which are primarily focused on client state, TanStack Query is purpose-built for managing server state. This removes the burden of manually handling caching, synchronization, and error management.

2. Smart Caching

TanStack Query automatically caches fetched data and only updates it when necessary. For example, if the same query is requested multiple times, it serves the cached result, significantly improving performance.

3. Automatic Data Updates

With features like refetching and background synchronization, the library ensures data always stays fresh. For instance, when a user navigates back to a page or refocuses the browser tab, TanStack Query automatically refreshes the data.

4. Server-Side Rendering (SSR) Support

In frameworks such as Next.js, TanStack Query provides built-in support for preloading data on the server, which improves SEO and speeds up page loads.

5. Intuitive API

The library offers a declarative and developer-friendly API, making code easier to write, read, and maintain.

Setting up TanStack Start and TanStack Router project:

Now it’s time to set up our React project, and TanStack Start is the perfect place to begin. First, navigate to a directory on your computer (for example, the desktop), and run the following commands to initialize your project:

mkdir tanstack-project
cd tanstack-project
npm create @tanstack/router@latest --legacy-peer-deps
npm run dev

With this script, we create a project directory called tanstack-project and install the required packages.

At the time of writing, TanStack Router requires React v18.3.1. If you have a newer version installed, you may encounter an error in the console. The simplest workaround is to use the --legacy-peer-deps flag, which bypasses peer dependency conflicts. For testing purposes, this approach is fine; however, in production, a more reliable solution is recommended.

Using TanStack Query for state management:

Now that we have global state management in place for our application, it’s time to set up TanStack Query. To get started, install the dependencies by running the following command in your terminal:

npm install @tanstack/react-query @tanstack/react-query-devtools

With these commands, we can now have access to a global state in our application.

Next, let’s build a simple blog using the free JSONPlaceholder API. The good news is that this requires changes in only two files. First, open the src/main.tsx file and replace its contents with the following code:

import React from 'react'
import ReactDOM from 'react-dom/client'
import { RouterProvider, createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'
import { 
  QueryClient, 
  QueryClientProvider 
} from '@tanstack/react-query'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5, 
      gcTime: 1000 * 60 * 60,
    },
  },
})

const router = createRouter({
  routeTree,
  defaultPreload: 'intent',
})

declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}
const rootElement = document.getElementById('app')!
if (!rootElement.innerHTML) {
  const root = ReactDOM.createRoot(rootElement)
  root.render(
    <React.StrictMode>
      <QueryClientProvider client={queryClient}>
        <RouterProvider router={router} />
        <ReactQueryDevtools initialIsOpen={false} />
      </QueryClientProvider>
    </React.StrictMode>
  )
}

This code initializes the React Query client and makes it available throughout the application. It also includes a few default query settings to improve the overall behavior.

Setting Up QueryClient:

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

const queryClient = new QueryClient();

ReactDOM.createRoot(document.getElementById('root')).render(
  <QueryClientProvider client={queryClient}>
    <App />
  </QueryClientProvider>
);

Fetching Data with useQuery:

// UsersList.jsx
import React from 'react';
import { useQuery } from '@tanstack/react-query';
import { fetchUsers } from './api';

function UsersList() {
  const { data, error, isLoading } = useQuery(['users'], fetchUsers);

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

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

export default UsersList;

Automatic Updates:

TanStack Query supports data refetching when a browser tab regains focus:

useQuery(['users'], fetchUsers, {
  refetchOnWindowFocus: true, // Refresh data when tab is refocused
});

Mutations for Data Modification:

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

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

  const mutation = useMutation(newUser => fetch('/api/users', {
    method: 'POST',
    body: JSON.stringify(newUser),
  }), {
    onSuccess: () => {
      // Refresh the cache after adding a new user
      queryClient.invalidateQueries(['users']);
    },
  });

  const handleAddUser = () => {
    mutation.mutate({ name: 'John Doe' });
  };

  return (
    <button onClick={handleAddUser} disabled={mutation.isLoading}>
      Add User
    </button>
  );
}

More Info
Related Blog