Chapter 4: Devtools

Core Idea

@tanstack/react-query-devtools is a separate package that visualizes every query/mutation's state live; it's excluded from production bundles by default, with an explicit lazy-load path for when you need it in prod too.

Key Concepts

Two render modes: Floating Mode mounts a toggleable overlay (state persisted in localStorage); Embedded Mode renders the panel as a normal element you control the visibility of yourself.
Auto dev-only inclusion: gated on process.env.NODE_ENV === 'development' — no manual stripping needed for normal builds. Next.js 13+ App Router needs it installed as a devDependency specifically for this to work.
Production access: lazy-load via React.lazy(() => import('@tanstack/react-query-devtools/production')) (or /build/modern/production.js on older bundlers) behind a manual toggle, e.g. window.toggleDevtools().
Shared options: client (custom QueryClient), errorTypes (predefined errors you can trigger from the UI), styleNonce (CSP), shadowDOMTarget, theme.
Browser extensions: Chrome/Firefox/Edge also have official devtools extensions offering the same functionality without adding a package.

Code Examples

// Floating mode — mount once, near the app root
<QueryClientProvider client={queryClient}>
  {children}
  <ReactQueryDevtools initialIsOpen={false} />
</QueryClientProvider>

// Embedded mode — you own the open/close state and placement
const [isOpen, setIsOpen] = React.useState(false)
;<ReactQueryDevtoolsPanel onClose={() => setIsOpen(false)} />

What it demonstrates: Floating mode for the common case (a toggle button in the corner); Embedded mode for building the toggle into your own dev tooling/panel.

Reference Tables

Option (both modes)	Purpose
`client`	Use a specific `QueryClient` instead of the nearest context one
`errorTypes`	Predefine errors triggerable from the devtools UI
`styleNonce`	CSP nonce for the injected style tag
`shadowDOMTarget`	Apply devtools styles inside a shadow root instead of `<head>`
`theme`	`"light" \| "dark" \| "system"` (default `system`)

Key Takeaways

Devtools are dev-only by default — reaching prod requires an explicit lazy-load wrapper, it's not automatic.
Since v5, the devtools also observe mutations, not just queries.
Place the devtools component as close to the app root as possible for the most reliable behavior.

Connects To

Installation: the devtools ship as a separate package from the core library.