tanstack-router

TanStack Router

React 向けの型安全なファイルベースルーティングです。ルートレベルのデータ読み込み、検索パラメーターの検証、コード分割、TanStack Query との統合に対応しています。

パッケージ： @tanstack/react-router | プラグイン： @tanstack/router-plugin

クイックリファレンス

パターン	用途
createFileRoute('/path')	ファイルベースのルートを定義する
createRootRouteWithContext<T>()	型付きコンテキストを持つルートを定義する
createLazyFileRoute('/path')	ルートコンポーネントをコード分割する
zodValidator(schema)	検索パラメーターを検証する
Route.useLoaderData()	コンポーネントでローダーデータにアクセスする
Route.useParams()	型安全なルートパラメーターを取得する
Route.useSearch()	型安全な検索パラメーターを取得する
useNavigate()	プログラムによるナビゲーション
useBlocker()	ナビゲーションをブロックする（未保存のフォーム）
notFound()	ローダーから 404 をスローする
getRouteApi('/path')	分割ファイルで型安全なフックを使う
stripSearchParams(defaults)	URL からデフォルト値を取り除く
retainSearchParams(['key'])	ナビゲーション間でパラメーターを保持する
useAwaited({ promise })	遅延されたプロミスが解決するまでサスペンドする
useCanGoBack()	ルーターで安全に戻れるか確認する

データ読み込み

メソッド	戻り値	スロー	用途
ensureQueryData	データ	はい	ルートローダー（推奨）
prefetchQuery	void	いいえ	バックグラウンドでのプリフェッチ
fetchQuery	データ	はい	データがすぐに必要な場合
defer()（任意）	Promise	いいえ	重要度の低いデータをストリーム配信する（プロミスは自動処理されます）

プリロード

戦略	動作	用途
'intent'	ホバー時／フォーカス時にプリロード	ほとんどのリンクのデフォルト
'render'	Link のマウント時にプリロード	次に表示する重要なページ
'viewport'	Link が表示範囲に入るとプリロード	画面下部のコンテンツ
false	プリロードしない	重く、訪問頻度の低いページ

ファイル構成

ファイル	目的
__root.tsx	<Outlet /> を持つルート
index.tsx	/ のインデックスルート
posts.$postId.tsx	動的パラメーターのルート
_authenticated.tsx	パスなしレイアウト（認証ガード）
dashboard.lazy.tsx	コード分割されたコンポーネント

よくある間違い

間違い	修正
ルーター型の登録漏れ	Register インターフェースを含む declare module を追加します
from を指定せずに useParams() を使用する	正確な型を得るため、常に from: '/route/path' を渡します
通常のリンクに useNavigate() を使用する	<a> タグ、アクセシビリティ、先読みには <Link> を使用します
ローダー内で prefetchQuery を使用する	ensureQueryData を使用します（データを返し、エラーをスローします）
useEffect でデータを取得する	ルートローダーを使用します（ウォーターフォールを防ぎます）
ローダー内で逐次的にデータを取得する	並列リクエストには Promise.all を使用します
先頭のスラッシュがない	常に 'about' ではなく '/about' を指定します
react() の後に TanStackRouterVite を配置する	Vite 設定ではプラグインを react() より前に配置する必要があります
strict: false でパラメーターが解析されない	厳密モードを使用するか、ナビゲーション後に手動で解析します
パスレスルートに notFoundComponent を設定する	代わりに子ルートに notFoundComponent を定義します
ローダーが中断されたときの未定義エラー	if (!error) return null で errorComponent をガードします
loaderDeps が宣言されていない	依存関係を宣言し、変更時にのみローダーが再実行されるようにします

委任

• TanStack Query のパターン — データ取得、キャッシュ、ミューテーション：tanstack-query スキルを使用します
• TanStack Start — サーバー関数、SSR、サーバーサイド認証：tanstack-start スキルを使用します
• TanStack Table — ルーターの検索パラメーターを使ったテーブル描画：tanstack-table スキルを使用します
• Router と Query の統合 — ローダーデータのフロー、先読み：ローダーデータのフローパターンを参照してください

tanstack-devtools スキルを利用できる場合は、ルーター状態のデバッグとルートツリーの調査を委任してください。

リファレンス

• セットアップ — インストール、Vite 設定、ファイル構成、アプリのセットアップ、ルーターのデフォルトオプション
• 型安全性 — ルーターの登録、from パラメーター、strict: false、型ユーティリティ、getRouteApi
• データ読み込み — ルートローダー、Query との統合、並列読み込み、ストリーミング、遅延データ、abort signal、loaderDeps
• 検索パラメーター — 検証、strip/retain ミドルウェア、細粒度のサブスクリプション、デバウンス、カスタムシリアライザー
• ナビゲーション — Link、アクティブスタイル、相対ナビゲーション、ハッシュ、ルートマスク、ブロッカー、スクロール復元
• 認証とコンテキスト — beforeLoad、コンテキストの継承、パスレスレイアウト、依存性注入、エラー処理
• コード分割 — 遅延ルート、自動分割、先読み戦略、プログラムによる先読み
• 仮想ファイルルート — rootRoute、route、index、layout、物理ビルダー、ファイルベースとコードベースのルーティングの併用
• 既知の問題 — 修正方法とアンチパターンを含む、文書化された20件の問題
• ローダーと Query のパターン — ローダー内の ensureQueryData、並列読み込み、重要データと重要でないデータ、検索パラメーターに依存するローダー