Open History to see the last commit
1---
2id: devtools
3title: Devtools
4---
5β
6Wave your hands in the air and shout hooray because React Query comes with dedicated devtools! π₯³
7β
8When you begin your React Query journey, you'll want these devtools by your side. They help visualize all of the inner workings of React Query and will likely save you hours of debugging if you find yourself in a pinch!
9β
10> Please note that for now, the devtools **do not support React Native**. If you would like to help us make the devtools platform agnostic, please let us know!
11β
12> Also note that you can use these devtools to observe queries, but **not mutations**
13β
14## Install and Import the Devtools
15β
16The devtools are a separate package that you need to install.
17β
18The major version of all the packages must be in sync.
19β
20```bash
21npm i @tanstack/react-query-devtools@4
22```
23β
24or
25β
26```bash
27pnpm add @tanstack/react-query-devtools@4
28```
29β
30or
31β
32```bash
33yarn add @tanstack/react-query-devtools@4
34```
35β
36You can import the devtools like this:
37β
38```tsx
39import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
40```
41β
42By default, React Query Devtools are only included in bundles when `process.env.NODE_ENV === 'development'`, so you don't need to worry about excluding them during a production build.
43β
44## Floating Mode
45β
46Floating Mode will mount the devtools as a fixed, floating element in your app and provide a toggle in the corner of the screen to show and hide the devtools. This toggle state will be stored and remembered in localStorage across reloads.
47β
48Place the following code as high in your React app as you can. The closer it is to the root of the page, the better it will work!
49β
50```tsx
51import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
52β
53function App() {
54 return (
55 <QueryClientProvider client={queryClient}>
56 {/* The rest of your application */}
57 <ReactQueryDevtools initialIsOpen={false} />
58 </QueryClientProvider>
59 )
60}
61```
62β
63### Options
64β
65- `initialIsOpen: Boolean`
66 - Set this `true` if you want the dev tools to default to being open
67- `panelProps: PropsObject`
68 - Use this to add props to the panel. For example, you can add `className`, `style` (merge and override default style), etc.
69- `closeButtonProps: PropsObject`
70 - Use this to add props to the close button. For example, you can add `className`, `style` (merge and override default style), `onClick` (extend default handler), etc.
71- `toggleButtonProps: PropsObject`
72 - Use this to add props to the toggle button. For example, you can add `className`, `style` (merge and override default style), `onClick` (extend default handler), etc.
73- `position?: "top-left" | "top-right" | "bottom-left" | "bottom-right"`
74 - Defaults to `bottom-left`
75 - The position of the React Query logo to open and close the devtools panel
76- `panelPosition?: "top" | "bottom" | "left" | "right"`
77 - Defaults to `bottom`
78 - The position of the React Query devtools panel
79- `context?: React.Context<QueryClient | undefined>`
80 - Use this to use a custom React Query context. Otherwise, `defaultContext` will be used.
81- `errorTypes?: { name: string; initializer: (query: Query) => { toString(): string }}`
82 - Use this to predefine some errors that can be triggered on your queries. Initializer will be called (with the specific query) when that error is toggled on from the UI. It must return an item that can be stringified so we can check for its presence on any given query.
83β
84## Embedded Mode
85β
86Embedded Mode will embed the devtools as a regular component in your application. You can style it however you'd like after that!
87β
88```tsx
89import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools'
90β
91function App() {
92 return (
93 <QueryClientProvider client={queryClient}>
94 {/* The rest of your application */}
95 <ReactQueryDevtoolsPanel style={styles} className={className} />
96 </QueryClientProvider>
97 )
98}
99```
100β
101### Options
102β
103Use these options to style the dev tools.
104β
105- `style: StyleObject`
106 - The standard React style object used to style a component with inline styles
107- `className: string`
108 - The standard React className property used to style a component with classes
109- `showCloseButton?: boolean`
110 - Show a close button inside the devtools panel
111- `closeButtonProps: PropsObject`
112 - Use this to add props to the close button. For example, you can add `className`, `style` (merge and override default style), `onClick` (extend default handler), etc.
113β
114## Devtools in production
115β
116Devtools are excluded in production builds. However, it might be desirable to lazy load the devtools in production:
117β
118```tsx
119import * as React from 'react'
120import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
121import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
122import { Example } from './Example'
123β
124const queryClient = new QueryClient()
125β
126const ReactQueryDevtoolsProduction = React.lazy(() =>
127 import('@tanstack/react-query-devtools/build/lib/index.prod.js').then(
128 (d) => ({
129 default: d.ReactQueryDevtools,
130 }),
131 ),
132)
133β
134function App() {
135 const [showDevtools, setShowDevtools] = React.useState(false)
136β
137 React.useEffect(() => {
138 // @ts-ignore
139 window.toggleDevtools = () => setShowDevtools((old) => !old)
140 }, [])
141β
142 return (
143 <QueryClientProvider client={queryClient}>
144 <Example />
145 <ReactQueryDevtools initialIsOpen />
146 {showDevtools && (
147 <React.Suspense fallback={null}>
148 <ReactQueryDevtoolsProduction />
149 </React.Suspense>
150 )}
151 </QueryClientProvider>
152 )
153}
154β
155export default App
156```
157β
158With this, calling `window.toggleDevtools()` will download the devtools bundle and show them.
159β
160### Modern bundlers
161β
162If your bundler supports package exports, you can use the following import path:
163β
164```tsx
165const ReactQueryDevtoolsProduction = React.lazy(() =>
166 import('@tanstack/react-query-devtools/production').then((d) => ({
167 default: d.ReactQueryDevtools,
168 })),
169)
170```
171β
172For TypeScript, you would need to set `moduleResolution: 'nodenext'` in your tsconfig, which requires at least TypeScript v4.7.