tanstack-devtools

概述

TanStack Devtools 提供统一的调试界面，将 TanStack Query、Router 和其他库的开发者工具整合到一个面板中。它采用与框架无关的插件架构，支持实时状态检查和自定义插件。基于 Solid.js 构建，性能轻量。

React： @tanstack/react-devtools Core： @tanstack/devtools 状态： Alpha

安装

npm install @tanstack/react-devtools

基本设置

import { TanStackDevtools } from '@tanstack/react-devtools'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

const queryClient = new QueryClient()

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <TanStackDevtools />
      {/* Your app content */}
      <MyApp />
    </QueryClientProvider>
  )
}

内置插件

Query Devtools

import { TanStackDevtools } from '@tanstack/react-devtools'
import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools'

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <TanStackDevtools
        plugins={[
          {
            id: 'react-query',
            name: 'React Query',
            render: () => <ReactQueryDevtoolsPanel />,
          },
        ]}
      />
      <MyApp />
    </QueryClientProvider>
  )
}

Router Devtools

import { TanStackDevtools } from '@tanstack/react-devtools'
import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools'

function App() {
  return (
    <TanStackDevtools
      plugins={[
        {
          id: 'router',
          name: 'Router',
          render: () => <TanStackRouterDevtoolsPanel router={router} />,
        },
      ]}
    />
  )
}

组合设置

import { TanStackDevtools } from '@tanstack/react-devtools'
import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools'
import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools'

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <TanStackDevtools
        plugins={[
          {
            id: 'react-query',
            name: 'React Query',
            render: () => <ReactQueryDevtoolsPanel />,
          },
          {
            id: 'router',
            name: 'Router',
            render: () => <TanStackRouterDevtoolsPanel router={router} />,
          },
        ]}
      />
      <MyApp />
    </QueryClientProvider>
  )
}

AI Devtools

用于调试 TanStack AI 工作流：

import { TanStackDevtools } from '@tanstack/react-devtools'
import { AIDevtoolsPanel } from '@tanstack/ai-react/devtools'

function App() {
  return (
    <TanStackDevtools
      plugins={[
        {
          id: 'ai',
          name: 'AI',
          render: () => <AIDevtoolsPanel />,
        },
      ]}
    />
  )
}

AI Devtools 功能：

• 消息检查器 - 查看包含元数据的完整对话历史
• Token 用量 - 跟踪每个请求的输入/输出 Token 数量和费用
• 流式可视化 - 实时查看流式数据块
• 工具调用调试 - 检查工具调用、参数和结果
• 思考/推理查看器 - 调试思考模型生成的推理 Token
• 适配器切换 - 在开发过程中测试不同的提供方

插件系统

插件接口

interface DevtoolsPlugin {
  id: string          // Unique identifier
  name: string        // Display name in the devtools panel
  render: () => JSX.Element  // React component to render
}

自定义插件

import { TanStackDevtools } from '@tanstack/react-devtools'

// Custom state inspector plugin
const stateInspectorPlugin = {
  id: 'state-inspector',
  name: 'State',
  render: () => (
    <div style={{ padding: '16px' }}>
      <h3>Application State</h3>
      <pre>{JSON.stringify(appState, null, 2)}</pre>
    </div>
  ),
}

// Custom network logger plugin
const networkLoggerPlugin = {
  id: 'network-logger',
  name: 'Network',
  render: () => <NetworkLoggerPanel />,
}

function App() {
  return (
    <TanStackDevtools
      plugins={[
        stateInspectorPlugin,
        networkLoggerPlugin,
      ]}
    />
  )
}

动态注册插件

function App() {
  const [plugins, setPlugins] = useState<DevtoolsPlugin[]>([])

  useEffect(() => {
    // Register plugins conditionally
    const activePlugins: DevtoolsPlugin[] = []

    if (process.env.NODE_ENV === 'development') {
      activePlugins.push({
        id: 'debug',
        name: 'Debug',
        render: () => <DebugPanel />,
      })
    }

    setPlugins(activePlugins)
  }, [])

  return <TanStackDevtools plugins={plugins} />
}

Vite 插件集成

// vite.config.ts
import { defineConfig } from 'vite'
import { tanstackDevtools } from '@tanstack/devtools/vite'

export default defineConfig({
  plugins: [
    tanstackDevtools(),
  ],
})

生产环境注意事项

// Only include devtools in development
function App() {
  return (
    <>
      {process.env.NODE_ENV === 'development' && (
        <TanStackDevtools plugins={plugins} />
      )}
      <MyApp />
    </>
  )
}

// Or use lazy loading
const TanStackDevtools = lazy(() =>
  import('@tanstack/react-devtools').then((m) => ({ default: m.TanStackDevtools }))
)

框架支持

框架	包	状态
React	@tanstack/react-devtools	Alpha
Solid	@tanstack/solid-devtools	Planned
Vue	@tanstack/vue-devtools	Planned
Angular	@tanstack/angular-devtools	Planned

功能

• 统一面板 - 用于所有 TanStack 调试的单一界面
• 实时更新 - 实时监控状态变化
• 插件架构 - 可通过自定义和第三方插件扩展
• 内置插件 - Query、Router 和 AI 开发者工具面板
• 轻量 - 基于 Solid.js 构建，开销极小
• 类型安全 - 为插件定义提供完整的 TypeScript 支持
• 与框架无关的核心 - 插件逻辑可跨框架使用

最佳实践

1. 在生产环境中按需启用 - 使用环境检查或代码拆分
2. 使用特定插件，而不是加载所有可用插件
3. 为插件设置唯一 ID，以避免冲突
4. 让插件渲染函数保持轻量 - 避免耗费大量资源的计算
5. 在基于 Vite 的项目中使用 Vite 插件，实现自动设置
6. 组合使用 Query + Router + AI 插件，进行全栈 TanStack 调试
7. 创建特定领域的插件，检查应用级状态
8. 在调试流式传输、工具调用或 Token 用量时使用 AI 开发者工具

常见问题

• 构建生产版本时未进行 tree-shaking，导致包含开发者工具
• 使用重复的插件 ID（会导致渲染冲突）
• 插件中的渲染函数过于复杂（会拖慢开发者工具面板）
• 使用 Query 插件时忘记用 QueryClientProvider 包装
• 未将路由器实例传递给 Router 开发者工具面板