tanstack-devtools

TanStack DevTools

概要

TanStack DevTools は、React アプリケーションで Query キャッシュの状態、Router のルートツリー、Form のフィールド状態を調査するためのデバッグパネルを提供します。利用方法は 2 つあります。各ライブラリの単体 DevTools（ReactQueryDevtools、TanStackRouterDevtools）と、プラグインアーキテクチャを備え、すべてのライブラリを 1 つのインターフェースに統合する統合 TanStack DevToolsパネルです。

使用する場面： TanStack ライブラリの DevTools をセットアップするとき、Query キャッシュの動作をデバッグするとき、ルートのマッチングを調査するとき、Form フィールドの状態を監視するとき、または複数の TanStack DevTools を 1 つのパネルにまとめるときに使用します。

使用しない場面： 本番環境でのデバッグ（デフォルトでは本番環境で DevTools がツリーシェイクされます）、アダプターに対応していない React 以外のフレームワーク、または TanStack ライブラリとは無関係なカスタム状態管理には使用しません。

クイックリファレンス

パターン	API	主なポイント
Query DevTools（フローティング）	<ReactQueryDevtools />	最も近い QueryClient に自動接続します
Query DevTools（埋め込み）	<ReactQueryDevtoolsPanel />	カスタムレイアウトに埋め込みます
Router DevTools（フローティング）	<TanStackRouterDevtools />	ルートコンポーネントに配置します
Router DevTools（埋め込み）	<TanStackRouterDevtoolsPanel />	Provider の外では router prop が必要です
Form DevTools	<ReactFormDevtoolsPanel />	統合 DevTools 用プラグイン
統合 DevTools	<TanStackDevtools plugins={[...]} />	すべての TanStack ライブラリを 1 つのパネルで表示します
Vite プラグイン	Vite 設定の devtools()	ソースコードの挿入、強化されたログ、本番環境での削除
本番 DevTools	ReactQueryDevtoolsInProd	本番環境での使用を明示的に有効化します
遅延読み込み	React.lazy(() => import(...))	開発時のバンドルサイズを削減します
開くためのホットキー	config={{ openHotkey: ['Shift', 'D'] }}	統合パネルを開くキーボードショートカット

統合 DevTools の設定

オプション	型	用途
position	'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'middle-left' | 'middle-right'	トリガーボタンの位置
panelLocation	'top' | 'bottom'	パネルがスライドする方向
theme	'dark' | 'light'	パネルの配色
defaultOpen	boolean	読み込み時にパネルを開く
hideUntilHover	boolean	ホバーするまでトリガーを非表示にする
openHotkey	KeyboardKey[]	パネルを切り替えるショートカット
inspectHotkey	KeyboardKey[]	ソースインスペクターのショートカット
requireUrlFlag	boolean	URL パラメーターがある場合にのみ有効化する

よくある間違い

間違い	正しいパターン
本番バンドルに開発ツールをインポートする	単独の開発ツールは自動的にツリーシェイキングされます。コード分割には React.lazy を使用します
RouterProvider 内で router プロパティを渡す	router プロパティは省略します。開発ツールがコンテキストを自動検出します
パネルの配置に ReactQueryDevtools の position を使う	buttonPosition はロゴの位置を制御し、position はパネルの端を制御します
単独の開発ツールと統合開発ツールを混在させる	どちらか一方を選択します。両方をレンダリングするとパネルが重複します
QueryClientProvider の外で開発ツールをレンダリングする	ReactQueryDevtools をプロバイダー内に配置するか、client プロパティを渡します
ルートツリーの外で TanStackRouterDevtools をレンダリングする	ルートコンポーネントに配置するか、router プロパティを明示的に渡します
統合開発ツール用の Vite プラグインを忘れる	@tanstack/devtools-vite の devtools() を Vite の設定に追加します
フレームワークアダプターなしで統合開発ツールを使う	@tanstack/react-devtools とライブラリ固有のプラグインパッケージを両方インストールします

委任

• 開発ツールのセットアップ確認：Task エージェントを使って、適切な配置と設定を確認します
• バンドルサイズの分析：Explore エージェントを使って、本番環境で開発ツールがツリーシェイキングされることを確認します
• コードレビュー：code-reviewer エージェントに委任します

tanstack-query スキルが利用可能な場合は、クエリ固有のデバッグパターンをそのスキルに委任します。 それ以外の場合は、次を推奨します：npx skills add oakoss/agent-skills --skill tanstack-query

tanstack-router スキルが利用可能な場合は、ルートのデバッグパターンをそのスキルに委任します。 それ以外の場合は、次を推奨します：npx skills add oakoss/agent-skills --skill tanstack-router

tanstack-form スキルが利用可能な場合は、フォームの状態管理と検証のパターンをそのスキルに委任します。

参考資料

• Query の開発ツールのセットアップ、モード、オプション
• Router の開発ツールのセットアップ、ルートの検査、オプション
• Form の開発ツールと統合開発ツールのパターン