TanStack DevTools
Overview
TanStack DevTools provides debugging panels for inspecting Query cache state, Router route trees, and Form field state in React applications. There are two approaches: standalone devtools per library (ReactQueryDevtools, TanStackRouterDevtools) and the unified TanStack Devtools panel that combines all libraries into a single interface with plugin architecture.
When to use: Setting up devtools for TanStack libraries, debugging query cache behavior, inspecting route matching, monitoring form field state, or combining multiple TanStack devtools into one panel.
When NOT to use: Production debugging (devtools are tree-shaken in production by default), non-React frameworks without adapter support, or custom state management unrelated to TанStack libraries.
Quick Reference
| Pattern | API | Key Points |
|---|---|---|
| Query devtools (floating) | <ReactQueryDevtools /> | Auto-connects to nearest QueryClient |
| Query devtools (embedded) | <ReactQueryDevtoolsPanel /> | Embed in custom layout |
| Router devtools (floating) | <TanStackRouterDevtools /> | Place in root route component |
| Router devtools (embedded) | <TanStackRouterDevtoolsPanel /> | Requires router prop outside provider |
| Form devtools | <ReactFormDevtoolsPanel /> | Plugin for unified devtools |
| Unified devtools | <TanStackDevtools plugins={[...]} /> | Single panel for all TanStack libraries |
| Vite plugin | devtools() in vite config | Source injection, enhanced logs, production removal |
| Production devtools | ReactQueryDevtoolsInProd | Opt-in for production environments |
| Lazy loading | React.lazy(() => import(...)) | Reduce bundle size in development |
| Open hotkey | config={{openHotkey: ['Shift', 'D']}} | Keyboard shortcut for unified panel |
Unified Devtools Config
| Option | Type | Purpose | |||||
|---|---|---|---|---|---|---|---|
position | `'top-left' \ | 'top-right' \ | 'bottom-left' \ | 'bottom-right' \ | 'middle-left' \ | 'middle-right'` | Trigger button location |
panelLocation | `'top' \ | 'bottom'` | Panel slide direction | ||||
theme | `'dark' \ | 'light'` | Panel color scheme | ||||
defaultOpen | boolean | Open panel on load | |||||
hideUntilHover | boolean | Hide trigger until hover | |||||
openHotkey | KeyboardKey[] | Toggle panel shortcut | |||||
inspectHotkey | KeyboardKey[] | Source inspector shortcut | |||||
requireUrlFlag | boolean | Only activate with URL parameter |
Common Mistakes
| Mistake | Correct Pattern |
|---|---|
| Importing devtools in production bundle | Standalone devtools auto-tree-shake; use React.lazy for code-splitting |
Passing router prop when inside RouterProvider | Omit router prop; devtools auto-detect context |
Using ReactQueryDevtools position for panel placement | buttonPosition controls logo position; position controls panel edge |
| Mixing standalone and unified devtools | Choose one approach; both rendering causes duplicate panels |
| Rendering devtools outside QueryClientProvider | Place ReactQueryDevtools inside provider or pass client prop |
Using TanStackRouterDevtools outside route tree | Place in root route component or pass router prop explicitly |
| Forgetting Vite plugin for unified devtools | Add devtools() from @tanstack/devtools-vite to vite config |
| Using unified devtools without framework adapter | Install both @tanstack/react-devtools and library-specific plugin packages |
Delegation
- Devtools setup review: Use
Taskagent to verify correct placement and configuration - Bundle size analysis: Use
Exploreagent to check devtools are tree-shaken in production - Code review: Delegate to
code-revieweragent
If thetanstack-queryskill is available, delegate query-specific debugging patterns to it. Otherwise, recommend:npx skills add oakoss/agent-skills --skill tanstack-queryIf thetanstack-routerskill is available, delegate route debugging patterns to it. Otherwise, recommend:npx skills add oakoss/agent-skills --skill tanstack-routerIf thetanstack-formskill is available, delegate form state management and validation patterns to it.