Open History to see the last commit
1---
2id: devtools
3title: Devtools
4---
5β
6> For Chrome, Firefox, and Edge users: Third-party browser extensions are available for debugging TanStack Query directly in browser DevTools. These provide the same functionality as the framework-specific devtools packages:
7>
8> - <img alt="Chrome logo" src="https://www.google.com/chrome/static/images/chrome-logo.svg" width="16" height="16" class="inline mr-1 not-prose" /> <a href="https://chromewebstore.google.com/detail/tanstack-query-devtools/annajfchloimdhceglpgglpeepfghfai">Devtools for Chrome</a>
9> - <img alt="Firefox logo" src="https://upload.wikimedia.org/wikipedia/commons/a/a0/Firefox_logo%2C_2019.svg" width="16" height="16" class="inline mr-1 not-prose" /> <a href="https://addons.mozilla.org/en-US/firefox/addon/tanstack-query-devtools/">Devtools for Firefox</a>
10> - <img alt="Edge logo" src="https://upload.wikimedia.org/wikipedia/commons/9/98/Microsoft_Edge_logo_%282019%29.svg" width="16" height="16" class="inline mr-1 not-prose" /> <a href="https://microsoftedge.microsoft.com/addons/detail/tanstack-query-devtools/edmdpkgkacmjopodhfolmphdenmddobj">Devtools for Edge</a>
11β
12## Enable devtools
13β
14Add the devtools package (in addition to `@tanstack/angular-query`):
15β
16```sh
17npm install @tanstack/angular-query-devtools
18```
19β
20The devtools help you debug and inspect your queries and mutations. You can enable the devtools by adding `withDevtools` to `provideTanStackQuery`.
21β
22By default, Angular Query Devtools only load in development.
23β
24```ts
25import { QueryClient, provideTanStackQuery } from '@tanstack/angular-query'
26import { withDevtools } from '@tanstack/angular-query-devtools'
27β
28export const appConfig: ApplicationConfig = {
29 providers: [provideTanStackQuery(() => new QueryClient(), withDevtools())],
30}
31```
32β
33## Devtools in production
34β
35If you need the real implementation in production, import from the `production` entrypoint.
36β
37```ts
38import { withDevtools } from '@tanstack/angular-query-devtools/production'
39```
40β
41To control when devtools are rendered, use the `loadDevtools` option.
42β
43When omitted or set to `'auto'`, devtools are only rendered in development mode.
44β
45```ts
46import { withDevtools } from '@tanstack/angular-query-devtools'
47β
48providers: [provideTanStackQuery(() => new QueryClient(), withDevtools())]
49β
50// which is equivalent to
51providers: [
52 provideTanStackQuery(
53 () => new QueryClient(),
54 withDevtools(() => ({ loadDevtools: 'auto' })),
55 ),
56]
57```
58β
59When setting the option to true, the devtools will be rendered in both development and production mode.
60β
61This is useful if you want to load devtools based on [Angular environment configurations](https://angular.dev/tools/cli/environments). E.g. you could set this to true when the application is running on your production build staging environment.
62β
63```ts
64// Make sure to use the production sub-path to load devtools in production builds
65import { withDevtools } from '@tanstack/angular-query-devtools/production'
66import { environment } from './environments/environment'
67β
68providers: [
69 provideTanStackQuery(
70 () => new QueryClient(),
71 withDevtools(() => ({ loadDevtools: environment.loadDevtools })),
72 ),
73]
74```
75β
76When setting the option to false, the devtools will not be rendered.
77β
78```ts
79providers: [
80 provideTanStackQuery(
81 () => new QueryClient(),
82 withDevtools(() => ({ loadDevtools: false })),
83 ),
84]
85```
86β
87### Webpack file replacements
88β
89Some webpack-based Angular builders do not apply package export conditions when
90they bundle application code. Use the explicit `production` and `stub`
91entrypoints with Angular CLI file replacements to keep the devtools dependency
92out of production bundles.
93β
94Create an application-level import that can be replaced:
95β
96```ts
97// src/app/query-devtools.ts
98export { withDevtools } from '@tanstack/angular-query-devtools/production'
99```
100β
101```ts
102// src/app/query-devtools.stub.ts
103export { withDevtools } from '@tanstack/angular-query-devtools/stub'
104```
105β
106Import the application-level module from your config:
107β
108```ts
109import { withDevtools } from './query-devtools'
110```
111β
112Then configure the production build:
113β
114```json
115{
116 "configurations": {
117 "production": {
118 "fileReplacements": [
119 {
120 "replace": "src/app/query-devtools.ts",
121 "with": "src/app/query-devtools.stub.ts"
122 }
123 ]
124 }
125 }
126}
127```
128β
129The same pattern is available for the [embedded panel](#embedded-mode):
130`@tanstack/angular-query-devtools/devtools-panel/production` and
131`@tanstack/angular-query-devtools/devtools-panel/stub`.
132β
133## Reactive options
134β
135Mutable options can be Angular signals. For example, a signal derived from a keyboard shortcut can show devtools on demand:
136β
137```ts
138import { Injectable, isDevMode } from '@angular/core'
139import { toSignal } from '@angular/core/rxjs-interop'
140import { fromEvent, map, scan } from 'rxjs'
141β
142@Injectable({ providedIn: 'root' })
143export class DevtoolsOptionsManager {
144 loadDevtools = toSignal(
145 fromEvent<KeyboardEvent>(document, 'keydown').pipe(
146 map(
147 (event): boolean =>
148 event.metaKey && event.ctrlKey && event.shiftKey && event.key === 'D',
149 ),
150 scan((acc, curr) => acc || curr, isDevMode()),
151 ),
152 {
153 initialValue: isDevMode(),
154 },
155 )
156}
157```
158β
159The callback runs once in an Angular injection context, so it can call
160`inject()`. Return signals as option values to update them reactively:
161β
162```ts
163// ...
164// π Import from the production sub-path to make devtools available in production builds
165import { inject } from '@angular/core'
166import { withDevtools } from '@tanstack/angular-query-devtools/production'
167β
168export const appConfig: ApplicationConfig = {
169 providers: [
170 provideHttpClient(),
171 provideTanStackQuery(
172 () => new QueryClient(),
173 withDevtools(() => ({
174 loadDevtools: inject(DevtoolsOptionsManager).loadDevtools,
175 })),
176 ),
177 ],
178}
179```
180β
181### Options returned from the callback
182β
183`loadDevtools`, `client`, `position`, `errorTypes`, `buttonPosition`,
184`initialIsOpen`, and `theme` accept either their documented static value or a
185signal containing that value.
186β
187`styleNonce`, `shadowDOMTarget`, `trustedTypesPolicy`, and `hideDisabledQueries`
188are construction-time options and do not accept signals.
189β
190- `loadDevtools?: 'auto' | boolean`
191 - Omit or `'auto'`: load devtools only in development mode.
192 - Use this to control whether devtools load when using the `/production` import.
193- `initialIsOpen?: Boolean`
194 - Set this to `true` if you want the tools to default to being open
195- `buttonPosition?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "relative"`
196 - Defaults to `bottom-right`
197 - The position of the TanStack logo to open and close the devtools panel
198 - If `relative`, the button is placed in the location that you render the devtools.
199- `position?: "top" | "bottom" | "left" | "right"`
200 - Defaults to `bottom`
201 - The position of the Angular Query devtools panel
202- `client?: QueryClient`,
203 - Use this to use a custom QueryClient. Otherwise, the QueryClient provided through `provideTanStackQuery` will be injected.
204- `errorTypes?: { name: string; initializer: (query: Query) => TError}[]`
205 - 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 Error.
206- `styleNonce?: string`
207 - Deprecated. The devtools no longer add a `<style>` element, so they need no nonce. This option does nothing.
208- `shadowDOMTarget?: ShadowRoot`
209 - The shadow root to add the devtools styles to. By default, the styles are added to the shadow root the devtools render in, or to the document when they do not render in a shadow root.
210- `trustedTypesPolicy?: { createHTML: (html: string) => unknown }`
211 - The Trusted Types policy the devtools use to create their HTML templates. Pass one when your page enforces `require-trusted-types-for 'script'`. The devtools only pass it their own markup, so a policy that returns its input is enough, for example `trustedTypes.createPolicy('devtools', { createHTML: (html) => html })`.
212- `hideDisabledQueries?: boolean`
213 - Defaults to `false`.
214 - Set this to true to hide disabled queries from the devtools panel.
215- `theme?: "light" | "dark" | "system"`
216 - Defaults to the theme selected in the devtools Settings menu, or `system` if none is selected.
217 - Sets the theme of the devtools panel, overriding the Settings menu selection.
218β
219## Embedded Mode
220β
221Embedded mode will show the development tools as a fixed element in your application, so you can use our panel in your own development tools.
222β
223Use `injectDevtoolsPanel` to render the devtools panel inside an element of your component. Like `withDevtools`, it is only included in development mode bundles. To use it in production builds, import it from `@tanstack/angular-query-devtools/devtools-panel/production`.
224β
225```angular-ts
226import { Component, signal, viewChild } from '@angular/core'
227import { injectDevtoolsPanel } from '@tanstack/angular-query-devtools/devtools-panel'
228import type { ElementRef } from '@angular/core'
229β
230@Component({
231 selector: 'app-root',
232 template: `
233 <button type="button" (click)="isOpen.set(!isOpen())">
234 {{ isOpen() ? 'Close' : 'Open' }} the devtools panel
235 </button>
236 @if (isOpen()) {
237 <div #div style="height: 500px"></div>
238 }
239 `,
240})
241export class AppComponent {
242 readonly isOpen = signal(false)
243 readonly divEl = viewChild<ElementRef>('div')
244β
245 readonly devtools = injectDevtoolsPanel(() => ({
246 hostElement: this.divEl(),
247 onClose: () => this.isOpen.set(false),
248 }))
249}
250```
251β
252`injectDevtoolsPanel` must be called in an injection context. To create the panel later, for example after lazy loading the entry point, wrap the call in [`runInInjectionContext`](https://angular.dev/api/core/runInInjectionContext). It returns a `DevtoolsPanelRef`; call its `destroy()` to remove the panel before the injector that created it is destroyed.
253β
254See the [devtools panel example](./examples/devtools-panel-angular-router) for both variants.
255β
256### Options
257β
258The callback is reactive: `hostElement`, `client`, `errorTypes`, `onClose`, and `theme` are applied whenever a signal read in the callback changes.
259β
260`styleNonce`, `shadowDOMTarget`, `trustedTypesPolicy`, and `hideDisabledQueries`
261are construction-time options, read when the panel is created.
262β
263- `hostElement?: ElementRef | null`
264 - The element to render the devtools panel in. When it is `undefined` or `null`, the devtools panel is not created, or is destroyed if it exists.
265- `onClose?: () => unknown`
266 - Callback function that is called when the devtools panel is closed
267- `client?: QueryClient`,
268 - Use this to use a custom QueryClient. Otherwise, the QueryClient provided through `provideTanStackQuery` will be injected.
269- `errorTypes?: { name: string; initializer: (query: Query) => TError}[]`
270 - 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 Error.
271- `styleNonce?: string`
272 - Deprecated. The devtools no longer add a `<style>` element, so they need no nonce. This option does nothing.
273- `shadowDOMTarget?: ShadowRoot`
274 - The shadow root to add the devtools styles to. By default, the styles are added to the shadow root the devtools render in, or to the document when they do not render in a shadow root.
275- `trustedTypesPolicy?: { createHTML: (html: string) => unknown }`
276 - The Trusted Types policy the devtools use to create their HTML templates. Pass one when your page enforces `require-trusted-types-for 'script'`. The devtools only pass it their own markup, so a policy that returns its input is enough, for example `trustedTypes.createPolicy('devtools', { createHTML: (html) => html })`.
277- `hideDisabledQueries?: boolean`
278 - Defaults to `false`.
279 - Set this to true to hide disabled queries from the devtools panel.
280- `theme?: "light" | "dark" | "system"`
281 - Defaults to the theme selected in the devtools Settings menu, or `system` if none is selected.
282 - Sets the theme of the devtools panel, overriding the Settings menu selection.
283β
284## Filter queries and mutations
285β
286The **Filter** input above the query and mutation lists uses the **Key** scope by default. Select the scope button inside the input to switch between **Key**, **Data**, and **All**:
287β
288- **Key** matches the query hash, or the mutation key and submission time.
289- **Data** matches the query data, or the mutation variables or data, the same way **Search data** does below.
290- **All** matches either.
291β
292The selected scope is remembered across reloads, like the other filter settings.
293β
294## Search query and mutation data
295β
296Select a query or mutation and use **Search data** in its Data Explorer to search nested property names and primitive values. Search uses case-insensitive text matching and treats special characters as plain text.
297β
298Matching text is highlighted. Matching editable values have a highlighted input. The explorer opens matching branches and the first matching page in each paginated collection. Other pages with matches are highlighted so you can open them. You can still inspect other rows and edit query data.
299β
300The Data Explorer highlights up to 1,000 matches at a time.
301β
302Select **Clear** or press **Escape** in the search field to restore your manual expansion. Selecting another query or mutation clears the search, unless the filter scope is **Data** or **All**: then the search starts with the filter text. For a mutation, it starts only in the variables or data that match the filter.