Install devtools package
Install @tanstack/react-query-devtools using npm, pnpm, yarn, or bun. For Next 13+ App Dir, install it as a dev dependency.
TanStack Query · React · all subjects
devtools
26 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Devtools production build exclusion
By default, React Query Devtools are automatically excluded from production bundles when process.env.NODE_ENV is not 'development', so you do not need to manually exclude them during a production build.
Browser extensions for TanStack Query debugging
Browser extensions are available for Chrome, Firefox, and Edge that provide devtools functionality directly in browser DevTools with the same features as the framework-specific packages.
React Native devtools tool
For React Native users, a third-party native macOS app called rn-better-dev-tools is available for debugging React Query in any js-based application, allowing real-time monitoring of queries across devices.
Devtools mutation support since v5
Since version 5, the devtools support observing mutations in addition to queries.
Floating Mode devtools setup
Floating Mode mounts the devtools as a fixed, floating element with a toggle in the corner of the screen. Place ReactQueryDevtools component as high in the React app as possible, preferably near the root, inside the QueryClientProvider.
Floating Mode devtools localStorage toggle state
In Floating Mode, the devtools toggle state is stored and remembered in localStorage across page reloads.
Floating Mode options
ReactQueryDevtools in Floating Mode accepts these options: initialIsOpen (boolean, default false), buttonPosition (string, default 'bottom-right', values: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'relative'), position (string, default 'bottom', values: 'top' | 'bottom' | 'left' | 'right'), client (QueryClient), errorTypes (array of {name: string, initializer: (query: Query) => TError}), styleNonce (string for CSP), shadowDOMTarget (ShadowRoot), theme (string, default 'system', values: 'light' | 'dark' | 'system').
Floating Mode example code
Example of Floating Mode devtools setup: ```tsx import { ReactQueryDevtools } from '@tanstack/react-query-devtools' function App() { return ( <QueryClientProvider client={queryClient}> {/* The rest of your application */} <ReactQueryDevtools initialIsOpen={false} /> </QueryClientProvider> ) } ```
Embedded Mode devtools setup
Embedded Mode shows the devtools as a fixed element in the application for integration into custom development tools. Place ReactQueryDevtoolsPanel component as high in the React app as possible, preferably near the root, inside the QueryClientProvider. Manually control visibility with state.
Embedded Mode options
ReactQueryDevtoolsPanel in Embedded Mode accepts these options: style (React.CSSProperties, default {height: '500px'}), onClose (callback function), client (QueryClient), errorTypes (array of {name: string, initializer: (query: Query) => TError}), styleNonce (string for CSP), shadowDOMTarget (ShadowRoot), theme (string, default 'system', values: 'light' | 'dark' | 'system').
Embedded Mode example code
Example of Embedded Mode devtools setup: ```tsx import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools' function App() { const [isOpen, setIsOpen] = React.useState(false) return ( <QueryClientProvider client={queryClient}> {/* The rest of your application */} <button onClick={() => setIsOpen(!isOpen)} >{`${isOpen ? 'Close' : 'Open'} the devtools panel`}</button> {isOpen && <ReactQueryDevtoolsPanel onClose={() => setIsOpen(false)} />} </QueryClientProvider> ) } ```
Lazy load devtools in production
To use devtools in production, lazy load them with React.lazy() and React.Suspense. Import from '@tanstack/react-query-devtools/build/modern/production.js' and conditionally render with a toggle function. This allows downloading the devtools bundle only when needed.
Production devtools lazy load example code
Example of lazy loading devtools in production: ```tsx import * as React from 'react' import { QueryClient, QueryClientProvider } from '@tanstack/react-query' import { ReactQueryDevtools } from '@tanstack/react-query-devtools' import { Example } from './Example' const queryClient = new QueryClient() const ReactQueryDevtoolsProduction = React.lazy(() => import('@tanstack/react-query-devtools/build/modern/production.js').then( (d) => ({ default: d.ReactQueryDevtools, }), ), ) function App() { const [showDevtools, setShowDevtools] = React.useState(false) React.useEffect(() => { // @ts-expect-error window.toggleDevtools = () => setShowDevtools((old) => !old) }, []) return ( <QueryClientProvider client={queryClient}> <Example /> <ReactQueryDevtools initialIsOpen /> {showDevtools && ( <React.Suspense fallback={null}> <ReactQueryDevtoolsProduction /> </React.Suspense> )} </QueryClientProvider> ) } export default App ```
Modern bundlers devtools import path
For bundlers that support package exports, import production devtools from '@tanstack/react-query-devtools/production' instead of the full build path. For TypeScript, set moduleResolution to 'nodenext' in tsconfig.json, which requires TypeScript v4.7 or later.
Devtools errorTypes option
The errorTypes option allows predefining errors that can be triggered on queries from the devtools UI. Each error type has a name string and an initializer function that takes a Query and returns an Error. The initializer is called when that error is toggled on from the UI.
Devtools styleNonce option
The styleNonce option accepts a string to pass a nonce to the style tag added to the document head. This is necessary when using a Content Security Policy (CSP) nonce to allow inline styles.
Devtools shadowDOMTarget option
The shadowDOMTarget option accepts a ShadowRoot to apply devtools styles within the shadow DOM instead of the head tag in the light DOM. By default, styles are applied to the head tag.
Devtools now bundled in main package
In React Query v3, devtools are included in the react-query package itself under the import react-query/devtools. Replace react-query-devtools imports with react-query/devtools.
Devtools mock offline behavior
TanStack Query Devtools show Queries in paused state if they would be fetching but have no network connection. The devtools has a toggle button to Mock offline behavior that sets the OnlineManager to offline state without actually affecting the network connection (which can be done separately in browser devtools).
broadcastQueryClient utility purpose
broadcastQueryClient is a utility for broadcasting and syncing the state of your queryClient between browser tabs and windows with the same origin.
broadcastQueryClient experimental status and breaking changes
broadcastQueryClient is currently in an experimental stage, which means breaking changes will happen in minor and patch releases. If relying on this in production during the experimental stage, you should lock your version to a patch-level version to avoid unexpected breakages.
broadcastQueryClient package import
The broadcastQueryClient utility comes as a separate package and is available under the '@tanstack/query-broadcast-client-experimental' import.
broadcastQueryClient basic usage
To use broadcastQueryClient, import the function and pass it your QueryClient instance, and optionally set a broadcastChannel. Example: broadcastQueryClient({ queryClient, broadcastChannel: 'my-app' })
BroadcastQueryClientOptions interface
BroadcastQueryClientOptions has the following properties: queryClient (QueryClient, required) - the QueryClient to sync; broadcastChannel (string, optional) - the unique channel name that will be used to communicate between tabs and windows; options (BroadcastChannelOptions, optional) - options for the BroadcastChannel API. The default broadcastChannel is 'tanstack-query'.
DevTools integration options for React Native
Three options are available for React Native DevTools integration: a native macOS app (rn-better-dev-tools), a Flipper plugin (react-query-native-devtools), and a Reactotron plugin (reactotron-react-query).