Devtools

Purpose and Scope

TanStack Query Devtools are debugging UI components for inspecting the query cache, observing active queries, and, since v5, watching mutations as well. They are meant to sit next to the application during development so that a developer can see what QueryClient is doing without adding temporary logging. The framework docs describe dedicated React and Preact packages, plus an Angular integration that is enabled through the Angular provider system. All three docs also point browser users to extension-based debugging for Chrome, Firefox, and Edge when an in-app component is not the preferred workflow.

Sources: docs/framework/angular/devtools.md, docs/framework/preact/devtools.md, docs/framework/react/devtools.md

Use this page when choosing which devtools package to install, deciding whether to mount a floating widget or embed a panel, or configuring production-only diagnostics. The core idea is consistent across frameworks: the devtools read from a QueryClient, visualize query and mutation state, and should be placed close to the QueryClient provider or registered with the framework-level provider. The integration details differ because React and Preact expose components, while Angular exposes provider features through provideTanStackQuery and withDevtools.

Relevant Source Files

• docs/framework/react/devtools.md - React Query Devtools guide covering installation commands, ReactQueryDevtools, development-bundle behavior, floating mode, options, browser extensions, React Native tooling, and mutation observation.
• docs/framework/preact/devtools.md - Preact Query Devtools guide covering the parallel @tanstack/preact-query-devtools package, PreactQueryDevtools, floating mode, options, and browser extension alternatives.
• docs/framework/angular/devtools.md - Angular Query Devtools guide covering withDevtools, development-mode inclusion, the production subpath, loadDevtools, and reactive option derivation through signals.

Installation and Environment Behavior

React and Preact ship their devtools as separate packages from the framework adapter. The React documentation installs @tanstack/react-query-devtools and imports ReactQueryDevtools; the Preact documentation installs @tanstack/preact-query-devtools and imports PreactQueryDevtools. The docs show equivalent package-manager commands for npm, pnpm, yarn, and bun, which makes the devtools an opt-in dependency rather than part of every Query installation. React applications using the Next 13+ App Router are called out specially: install the devtools as a development dependency so the expected development-only bundling behavior works.

npm i @tanstack/react-query-devtools
pnpm add @tanstack/preact-query-devtools

Sources: docs/framework/preact/devtools.md, docs/framework/react/devtools.md

By default, React and Preact Query Devtools are only included when process.env.NODE_ENV === 'development'. Angular uses the same developer-friendly default at the provider level: Angular Query Devtools are only included in development mode bundles unless you import the production subpath or explicitly load them. This default matters because devtools are highly useful during implementation but should not accidentally increase production bundles or expose diagnostic UI to end users. If production diagnostics are required, make that choice explicit in configuration rather than relying on a default development import.

Framework Integration Patterns

In React, mount the devtools under QueryClientProvider, preferably high in the component tree. The guide recommends placing it as close to the root of the page as possible because floating mode creates a fixed UI and needs access to the same QueryClient context as the rest of the application. The minimal setup is intentionally small: import ReactQueryDevtools, keep the normal application under QueryClientProvider, and render the devtools component beside the application tree. The component can also receive a client prop when the nearest context is not the QueryClient you want to inspect.

import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
 
function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <AppRoutes />
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  )
}

Sources: docs/framework/react/devtools.md

Preact follows the same mental model with Preact-native names. Install @tanstack/preact-query-devtools, import PreactQueryDevtools, and render it inside the QueryClientProvider. The Preact guide uses the same floating-mode language as React: the UI mounts as a fixed element, shows a corner toggle, and stores the open or closed state in localStorage so reloads remember the developer’s preference. That parity is useful when porting examples between React and Preact because the QueryClient relationship, placement recommendation, and primary options remain the same even though the import path changes.

import { PreactQueryDevtools } from '@tanstack/preact-query-devtools'
 
function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <AppRoutes />
      <PreactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  )
}

Sources: docs/framework/preact/devtools.md

Angular integrates through providers rather than rendered components. Add withDevtools to provideTanStackQuery when configuring the application. The same guide documents a production subpath, @tanstack/angular-query-experimental/devtools/production, for cases where a production build should be able to lazy-load the devtools. The option factory passed to withDevtools supports reactivity, so Angular apps can derive whether devtools are loaded from signals, environment configuration, or a keyboard shortcut rather than hard-coding a static boolean at bootstrap time.

import { QueryClient, provideTanStackQuery } from '@tanstack/angular-query-experimental'
import { withDevtools } from '@tanstack/angular-query-experimental/devtools'
 
export const appConfig = {
  providers: [provideTanStackQuery(new QueryClient(), withDevtools())],
}

Sources: docs/framework/angular/devtools.md

Runtime Modes, Panels, and Options

Floating mode is the default developer experience emphasized by the React and Preact docs. It mounts an in-app panel and a toggle button. The documented options control both visibility and layout: initialIsOpen chooses whether the panel starts open, buttonPosition controls where the TanStack logo toggle appears, and position controls the panel edge. React documents relative as a buttonPosition value for rendering the button where the devtools component is placed. Both React and Preact also document client, errorTypes, styleNonce, and shadowDOMTarget for advanced usage such as multiple QueryClients, test error injection, Content Security Policy nonces, and Shadow DOM styling.

The devtools package can also be used as a panel inside the broader TanStack Devtools shell. In that mode, the Query panel is composed with other TanStack panels through the shell’s plugin list rather than mounted only as a standalone floating widget. This is most relevant when an application already uses multiple TanStack libraries and wants one unified debug surface. The Query-specific docs remain the authority for Query options and QueryClient access, while the shared devtools shell provides the surrounding multi-panel container.

import { TanStackDevtools } from '@tanstack/react-devtools'
import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools'
 
<TanStackDevtools
  plugins={[
    {
      name: 'TanStack Query',
      render: <ReactQueryDevtoolsPanel />,
    },
  ]}
/>

Sources: docs/framework/react/devtools.md

For Angular, production and lazy-loading behavior is expressed with loadDevtools. If the option is omitted or set to auto, the docs describe development-mode loading. Setting it to true loads devtools in both development and production, which is useful for staging environments that use production builds. Setting it to false disables loading. Because options come from a callback, the Angular guide can support reactive decisions, including examples where a signal derived from an RxJS observable toggles devtools on demand.

provideTanStackQuery(
  new QueryClient(),
  withDevtools(() => ({ loadDevtools: 'auto' })),
)

Sources: docs/framework/angular/devtools.md

Browser and Native Debugging Alternatives

The framework docs consistently mention third-party browser extensions for Chrome, Firefox, and Edge. These extensions debug TanStack Query directly in browser DevTools and provide the same functionality as the framework-specific devtools packages. That makes them a good fit when you cannot or do not want to add a devtools component to the application bundle, such as debugging an already-running page or keeping application markup free of diagnostic UI. React documentation also points React Native users to a third-party native macOS app for observing Query across JavaScript-based applications and devices.

Sources: docs/framework/angular/devtools.md, docs/framework/preact/devtools.md, docs/framework/react/devtools.md

Choose the in-app package when you want configuration from source control, access to component options, or a panel that travels with local development. Choose browser extensions when you want a browser-native workflow without modifying application code. Choose the shared TanStack Devtools shell when Query is one of several TanStack libraries being debugged together. These choices are complementary: the same QueryClient state can be inspected through different surfaces, while production inclusion should remain deliberate and limited to the environments that need it.

Compact Reference

Next steps: install the package for your framework, mount or register the devtools at the same level as your QueryClient, and keep production loading behind an explicit environment or signal-based decision. If you are standardizing debugging across TanStack libraries, evaluate the shared TanStack Devtools shell and use the Query panel as one plugin in that broader interface.