Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 38 ยท Testing and DevTools

DevTools

Use the TanStack Query DevTools to see every query, its status, staleness and observers, trigger refetches and errors, and read the cache while you debug.

A cache you cannot see is hard to trust. Why did that component refetch? Is this data stale? Which queries are still in memory? The TanStack Query DevTools answer those questions with a panel that lists every query in the QueryClient, with its key, status, number of observers and last update time, and buttons to refetch, invalidate, reset or fake an error.

Most "TanStack Query is doing something strange" problems are solved within a minute of opening the panel. This lesson shows how to install it, how to read it and how to use it as a learning tool.

Installing

In a bundler project:

Terminal
npm install @tanstack/react-query-devtools
JSX
import { ReactQueryDevtools } from "@tanstack/react-query-devtools";

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

Place it inside the provider, anywhere in the tree. It renders a small floating button in a corner; click it to open the panel. The package is designed so that in production builds (process.env.NODE_ENV === "production") the component renders nothing and bundlers drop it, so you can leave it in. If you want it available in production for debugging, lazy-load the production export behind a flag.

Useful props: initialIsOpen, buttonPosition ("bottom-right", "top-left", and so on), position for the panel and client if you have several clients.

A live panel

The example below loads the real devtools. A small todo list gives it something to show: fetch the list, then use the mutate button to create a new key.

The real DevTools panel

If the panel does not appear, your browser may be blocking the CDN import; the rest of this lesson explains what you would see.

Reading the panel

Each query is a row with a colored badge and a number:

Colour State Meaning
Green fresh Data exists and is younger than staleTime
Yellow stale Data exists but is older than staleTime, so it refetches on the next trigger
Blue fetching A request is running right now
Grey inactive No component observes it; it will be removed after gcTime
Grey/paused paused Wants to fetch but is offline

The number is the count of observers: components using that key. 0 means inactive (waiting for garbage collection).

Click a row to see details: the key, the data (an expandable tree), the query's options and timestamps (last updated, how many times it fetched). Buttons on the detail pane let you:

  • Refetch the query.
  • Invalidate it (marks it stale and refetches if observed).
  • Reset it to its initial state.
  • Remove it from the cache.
  • Trigger loading and trigger error, which force the UI into a pending or failed state so you can test your loading skeletons and error boundaries without changing the server.

There are also toggles for offline mode (to see paused queries and isPaused) and a filter and sort bar.

Debugging recipes

"Why did this refetch?" Watch the row while you focus the window or remount the component. A refetch on window focus happens for every stale query with an observer. If the data should be fresh longer, raise staleTime.

"Why is my list not updating after a mutation?" Compare the key in the devtools with the key you invalidate. A mismatch such as ["todos", { page: 1 }] versus ["todo"] is the usual cause. Remember that invalidateQueries({ queryKey: ["todos"] }) matches by prefix, so it hits both ["todos"] and ["todos", 3].

"Why are there so many entries?" Inactive rows pile up for each distinct key (every search term, every page). They disappear after gcTime (5 minutes by default). Very high counts suggest a key containing something that changes on every render, such as a new object created with Date.now().

"Is my optimistic update right?" Open the data tree, trigger the mutation, and watch the cache change before the request returns. Then use "trigger error" on the mutation's request path and check the rollback.

"Is my loading UI correct?" Use trigger loading to freeze a query in the pending state and style it without slowing the API down.

Logging without the panel

DevTools are visual. For logs, tests and production tracing, subscribe to the cache yourself:

JS Subscribing to the QueryCache

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The event stream shows the life cycle of a query: added, fetch, success, invalidate, removed. The same data feeds the devtools. cache.getAll() returns every query for scripts and tests.

Beyond the React panel

  • Framework-agnostic: @tanstack/query-devtools mounts the same panel in Vue, Svelte, Solid, Angular or plain JavaScript.
  • Browser extension: community extensions show the cache without changing your code.
  • Persisted caches: if you use persistQueryClient, remember that old persisted data appears in the panel immediately after load, which explains "ghost" data after a deploy; use a buster string to invalidate it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a yellow query in the devtools mean?

    Yellow marks stale data: older than staleTime, so it refetches at the next trigger such as a focus or mount.
  2. 2. What does the observer count next to a query mean?

    Observers are the active users of the query; zero means inactive and eligible for garbage collection after gcTime.
  3. 3. Where should <ReactQueryDevtools /> be placed?

    It needs the client from the provider (or an explicit client prop).
  4. 4. How can you force a loading state to style a skeleton?

    The devtools can hold a query in a pending state without changing the API.

Summary

  • Install @tanstack/react-query-devtools and render ReactQueryDevtools inside the provider; production builds omit it.
  • Rows show status colors and observer counts; details show data, options and timestamps.
  • Use refetch, invalidate, reset, trigger loading and trigger error to test UI states.
  • Compare devtools keys with the keys you invalidate to solve most "not updating" bugs.
  • queryCache.subscribe gives you the same events in code.

Next: Testing Queries and Mutations