Back to Details

tanstack-devtools

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Overview

概述

TanStack Devtools provides a unified debugging interface that consolidates devtools for TanStack Query, Router, and other libraries into a single panel. It features a framework-agnostic plugin architecture, real-time state inspection, and support for custom plugins. Built with Solid.js for lightweight performance.
React: 
@tanstack/react-devtools
Core: 
@tanstack/devtools
Status: Alpha
TanStack Devtools 提供了一个统一的调试界面，将TanStack Query、Router等类库的开发者工具整合到单个面板中。它采用与框架无关的插件架构，支持实时状态检查，并且可自定义插件。基于Solid.js构建，兼顾轻量与性能。
React: 
@tanstack/react-devtools
Core: 
@tanstack/devtools
状态: 测试版（Alpha）

Installation

安装

bash
npm install @tanstack/react-devtools
bash
npm install @tanstack/react-devtools

Basic Setup

基础配置

tsx
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>
  )
}
tsx
import { TanStackDevtools } from '@tanstack/react-devtools'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

const queryClient = new QueryClient()

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <TanStackDevtools />
      {/* 你的应用内容 */}
      <MyApp />
    </QueryClientProvider>
  )
}

Built-in Plugins

内置插件

Query Devtools

Query 开发者工具

tsx
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>
  )
}
tsx
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

Router 开发者工具

tsx
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} />,
        },
      ]}
    />
  )
}
tsx
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} />,
        },
      ]}
    />
  )
}

Combined Setup

组合配置

tsx
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>
  )
}
tsx
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

AI 开发者工具

For debugging TanStack AI workflows:
tsx
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 features:
  • Message Inspector - View full conversation history with metadata
  • Token Usage - Track input/output tokens and costs per request
  • Streaming Visualization - Real-time view of streaming chunks
  • Tool Call Debugging - Inspect tool calls, parameters, and results
  • Thinking/Reasoning Viewer - Debug reasoning tokens from thinking models
  • Adapter Switching - Test different providers in development
用于调试TanStack AI工作流：
tsx
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 开发者工具功能：
  • 消息检查器 - 查看包含元数据的完整对话历史
  • Token使用统计 - 跟踪每个请求的输入/输出Token数量及成本
  • 流式可视化 - 实时查看流式数据块
  • 工具调用调试 - 检查工具调用、参数及结果
  • 思考/推理查看器 - 调试思考模型生成的推理Token
  • 适配器切换 - 在开发环境测试不同的服务提供商

Plugin System

插件系统

Plugin Interface

插件接口

typescript
interface DevtoolsPlugin {
  id: string          // Unique identifier
  name: string        // Display name in the devtools panel
  render: () => JSX.Element  // React component to render
}
typescript
interface DevtoolsPlugin {
  id: string          // 唯一标识符
  name: string        // 开发者工具面板中的显示名称
  render: () => JSX.Element  // 要渲染的React组件
}

Custom Plugins

自定义插件

tsx
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,
      ]}
    />
  )
}
tsx
import { TanStackDevtools } from '@tanstack/react-devtools'

// 自定义状态检查插件
const stateInspectorPlugin = {
  id: 'state-inspector',
  name: 'State',
  render: () => (
    <div style={{ padding: '16px' }}>
      <h3>应用状态</h3>
      <pre>{JSON.stringify(appState, null, 2)}</pre>
    </div>
  ),
}

// 自定义网络日志插件
const networkLoggerPlugin = {
  id: 'network-logger',
  name: 'Network',
  render: () => <NetworkLoggerPanel />,
}

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

Dynamic Plugin Registration

动态注册插件

tsx
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} />
}
tsx
function App() {
  const [plugins, setPlugins] = useState<DevtoolsPlugin[]>([])

  useEffect(() => {
    // 按需注册插件
    const activePlugins: DevtoolsPlugin[] = []

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

    setPlugins(activePlugins)
  }, [])

  return <TanStackDevtools plugins={plugins} />
}

Vite Plugin Integration

Vite插件集成

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

export default defineConfig({
  plugins: [
    tanstackDevtools(),
  ],
})
typescript
// vite.config.ts
import { defineConfig } from 'vite'
import { tanstackDevtools } from '@tanstack/devtools/vite'

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

Production Considerations

生产环境注意事项

tsx
// 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 }))
)
tsx
// 仅在开发环境引入开发者工具
function App() {
  return (
    <>
      {process.env.NODE_ENV === 'development' && (
        <TanStackDevtools plugins={plugins} />
      )}
      <MyApp />
    </>
  )
}

// 或使用懒加载
const TanStackDevtools = lazy(() =>
  import('@tanstack/react-devtools').then((m) => ({ default: m.TanStackDevtools }))
)

Framework Support

框架支持

FrameworkPackageStatus
React
@tanstack/react-devtools
Alpha
Solid
@tanstack/solid-devtools
Planned
Vue
@tanstack/vue-devtools
Planned
Angular
@tanstack/angular-devtools
Planned
框架包名状态
React
@tanstack/react-devtools
测试版（Alpha）
Solid
@tanstack/solid-devtools
规划中
Vue
@tanstack/vue-devtools
规划中
Angular
@tanstack/angular-devtools
规划中

Features

功能特性

  • Unified Panel - Single interface for all TanStack debugging
  • Real-time Updates - Live monitoring of state changes
  • Plugin Architecture - Extensible with custom and third-party plugins
  • Built-in Plugins - Query, Router, and AI devtools panels
  • Lightweight - Built with Solid.js for minimal overhead
  • Type-safe - Full TypeScript support for plugin definitions
  • Framework-agnostic Core - Plugin logic works across frameworks
  • 统一面板 - 所有TanStack调试工具的单一操作界面
  • 实时更新 - 实时监控状态变化
  • 插件架构 - 可通过自定义或第三方插件扩展功能
  • 内置插件 - 包含Query、Router和AI开发者工具面板
  • 轻量高效 - 基于Solid.js构建，性能开销极小
  • 类型安全 - 插件定义完全支持TypeScript
  • 框架无关核心 - 插件逻辑可跨框架复用

Best Practices

最佳实践

  1. Conditionally include in production - use environment checks or code splitting
  2. Use specific plugins rather than loading all available ones
  3. Give plugins unique IDs to prevent conflicts
  4. Keep plugin render functions lightweight - avoid expensive computations
  5. Use the Vite plugin for automatic setup in Vite-based projects
  6. Combine Query + Router + AI plugins for full-stack TanStack debugging
  7. Create domain-specific plugins for app-level state inspection
  8. Use AI devtools when debugging streaming, tool calls, or token usage
  1. 生产环境按需引入 - 使用环境变量检查或代码分割
  2. 使用特定插件 - 避免加载所有可用插件
  3. 为插件设置唯一ID - 防止冲突
  4. 保持插件渲染函数轻量 - 避免昂贵的计算操作
  5. 使用Vite插件 - 在基于Vite的项目中实现自动配置
  6. 组合Query + Router + AI插件 - 实现全栈TanStack调试
  7. 创建领域特定插件 - 用于应用级状态检查
  8. 调试AI工作流时使用AI开发者工具 - 处理流式传输、工具调用或Token使用场景

Common Pitfalls

常见误区

  • Including devtools in production builds without tree-shaking
  • Using duplicate plugin IDs (causes rendering conflicts)
  • Heavy render functions in plugins (slows down the devtools panel)
  • Forgetting to wrap with QueryClientProvider when using Query plugin
  • Not passing the router instance to Router devtools panel
  • 在生产构建中引入开发者工具却未启用摇树优化
  • 使用重复的插件ID（会导致渲染冲突）
  • 插件中使用重渲染函数（拖慢开发者工具面板）
  • 使用Query插件时忘记用QueryClientProvider包裹
  • 未向Router开发者工具面板传入router实例