tanstack-devtools

概要

TanStack Devtools は、TanStack Query、Router、その他のライブラリの開発者ツールを単一のパネルに集約した、統一されたデバッグインターフェースを提供します。フレームワークに依存しないプラグインアーキテクチャ、リアルタイムの状態検査、カスタムプラグインへの対応を備えています。軽量なパフォーマンスを実現するために Solid.js で構築されています。

React： @tanstack/react-devtools コア： @tanstack/devtools ステータス： アルファ版

インストール

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 の機能：

• メッセージインスペクター - メタデータを含む会話履歴全体を表示します
• トークン使用量 - リクエストごとの入出力トークン数とコストを追跡します
• ストリーミングの可視化 - ストリーミングチャンクをリアルタイムで確認できます
• ツール呼び出しのデバッグ - ツール呼び出し、パラメーター、結果を検査します
• 思考・推論ビューアー - 思考モデルの推論トークンをデバッグします
• アダプターの切り替え - 開発時にさまざまなプロバイダーをテストします

プラグインシステム

プラグインインターフェース

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	アルファ版
Solid	@tanstack/solid-devtools	予定
Vue	@tanstack/vue-devtools	予定
Angular	@tanstack/angular-devtools	予定

機能

• 統合パネル - TanStack のすべてのデバッグ機能を単一のインターフェースで利用できます
• リアルタイム更新 - 状態の変化をライブで監視します
• プラグインアーキテクチャ - カスタムプラグインやサードパーティ製プラグインで拡張できます
• 組み込みプラグイン - Query、Router、AI の開発者ツールパネルを備えています
• 軽量 - オーバーヘッドを最小限に抑えるために Solid.js で構築されています
• 型安全 - プラグイン定義を完全に TypeScript でサポートします
• フレームワーク非依存のコア - プラグインのロジックは複数のフレームワークで動作します

ベストプラクティス

1. 本番環境では条件付きで含める - 環境チェックまたはコード分割を使用します
2. すべての利用可能なプラグインを読み込むのではなく、特定のプラグインを使用します
3. 競合を防ぐため、プラグインには一意の ID を付けます
4. プラグインのレンダー関数は軽量に保つ - 負荷の高い計算は避けます
5. Vite ベースのプロジェクトで自動セットアップするには、Vite プラグインを使用します
6. フルスタックの TanStack デバッグには、Query、Router、AI のプラグインを組み合わせます
7. アプリケーションレベルの状態検査には、ドメイン固有のプラグインを作成します
8. ストリーミング、ツール呼び出し、トークン使用量をデバッグするときは、AI devtools を使用します

よくある落とし穴

• ツリーシェイキングを行わずに開発者ツールを本番ビルドに含める
• 重複したプラグイン ID を使用する（レンダリングの競合が発生します）
• プラグインのレンダー関数が重い（開発者ツールのパネルが遅くなります）
• Query プラグインを使用する際に、QueryClientProvider でラップし忘れる
• Router devtools パネルにルーターインスタンスを渡し忘れる