Back to Details

tanstack-devtools

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

TanStack DevTools

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.
TanStack DevTools 提供调试面板，用于检查 React 应用中的 Query 缓存状态、Router 路由树和 Form 字段状态。有两种使用方式：各库独立开发工具（
ReactQueryDevtools
、
TanStackRouterDevtools
），以及统一的 TanStack Devtools 面板，它通过插件架构将所有库整合到一个界面中。
适用场景：为 TanStack 系列库搭建开发工具、调试查询缓存行为、检查路由匹配情况、监控表单字段状态，或是将多个 TanStack 开发工具整合到单个面板中。
不适用场景：生产环境调试（开发工具默认会在生产环境中被 tree-shaken 移除）、无适配器支持的非 React 框架，或是与 TanStack 库无关的自定义状态管理。

Quick Reference

快速参考

PatternAPIKey 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
模式API核心要点
悬浮式 Query 开发工具
<ReactQueryDevtools />
自动连接到最近的 QueryClient
嵌入式 Query 开发工具
<ReactQueryDevtoolsPanel />
可嵌入自定义布局
悬浮式 Router 开发工具
<TanStackRouterDevtools />
放置在根路由组件中
嵌入式 Router 开发工具
<TanStackRouterDevtoolsPanel />
在 Provider 外部使用时需要传入 
router
属性
Form 开发工具
<ReactFormDevtoolsPanel />
统一开发工具的插件
统一开发工具
<TanStackDevtools plugins={[...]} />
单个面板整合所有 TanStack 系列库
Vite 插件
devtools()
in vite config		源码注入、增强日志、生产环境自动移除
生产环境开发工具
ReactQueryDevtoolsInProd
需手动开启才能在生产环境使用
懒加载
React.lazy(() => import(...))
减少开发环境下的包体积
打开快捷键
config={{ openHotkey: ['Shift', 'D'] }}
统一面板的键盘快捷键

Unified Devtools Config

统一开发工具配置

OptionTypePurpose
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
配置项类型用途
position
'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'middle-left' | 'middle-right'
触发按钮的位置
panelLocation
'top' | 'bottom'
面板滑出方向
theme
'dark' | 'light'
面板配色方案
defaultOpen
boolean
加载时是否默认打开面板
hideUntilHover
boolean
触发按钮仅在 hover 时显示
openHotkey
KeyboardKey[]
面板切换快捷键
inspectHotkey
KeyboardKey[]
源码检查器快捷键
requireUrlFlag
boolean
仅当 URL 带有指定参数时激活

Common Mistakes

常见错误

MistakeCorrect Pattern
Importing devtools in production bundleStandalone 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 devtoolsChoose one approach; both rendering causes duplicate panels
Rendering devtools outside QueryClientProviderPlace 
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 devtoolsAdd 
devtools()
from 
@tanstack/devtools-vite
to vite config
Using unified devtools without framework adapterInstall both 
@tanstack/react-devtools
and library-specific plugin packages
错误操作正确做法
在生产环境包中引入开发工具独立开发工具会自动被 tree-shake；使用 
React.lazy
进行代码分割
在 RouterProvider 内部使用时传入 
router
属性		省略 
router
属性；开发工具会自动检测上下文
用 
ReactQueryDevtools
的 
position
控制面板位置
buttonPosition
控制图标位置；
position
控制面板边缘位置
同时使用独立开发工具和统一开发工具选择其中一种方式；同时渲染会导致面板重复
在 QueryClientProvider 外部渲染开发工具将 
ReactQueryDevtools
放在 Provider 内部，或传入 
client
属性
在路由树外部使用 
TanStackRouterDevtools
放在根路由组件中，或显式传入 
router
属性
使用统一开发工具时忘记配置 Vite 插件在 vite 配置中添加 
@tanstack/devtools-vite
中的 
devtools()
方法
未安装框架适配器就使用统一开发工具同时安装 
@tanstack/react-devtools
和对应库的插件包

Delegation

任务委派

  • Devtools setup review: Use 
    Task
    agent to verify correct placement and configuration
  • Bundle size analysis: Use 
    Explore
    agent to check devtools are tree-shaken in production
  • Code review: Delegate to 
    code-reviewer
    agent
If the 
tanstack-query
skill is available, delegate query-specific debugging patterns to it. Otherwise, recommend: 
npx skills add oakoss/agent-skills --skill tanstack-query
If the 
tanstack-router
skill is available, delegate route debugging patterns to it. Otherwise, recommend: 
npx skills add oakoss/agent-skills --skill tanstack-router
If the 
tanstack-form
skill is available, delegate form state management and validation patterns to it.
  • 开发工具配置审核：使用 
    Task
    agent 验证放置位置和配置是否正确
  • 包体积分析：使用 
    Explore
    agent 检查开发工具是否在生产环境中被 tree-shaken 移除
  • 代码审核：委派给 
    code-reviewer
    agent
如果 
tanstack-query
skill 可用，将查询相关的调试模式委派给该 skill。 否则，推荐执行：
npx skills add oakoss/agent-skills --skill tanstack-query
如果 
tanstack-router
skill 可用，将路由调试模式委派给该 skill。 否则，推荐执行：
npx skills add oakoss/agent-skills --skill tanstack-router
如果 
tanstack-form
skill 可用，将表单状态管理和验证模式委派给该 skill。

References

参考资料

  • Query devtools setup, modes, and options
  • Router devtools setup, route inspection, and options
  • Form devtools and unified devtools patterns
  • Query 开发工具的配置、模式及可选参数
  • Router 开发工具的配置、路由检查及可选参数
  • Form 开发工具及统一开发工具使用模式