router-core

TanStack Router Core

TanStack Router は、SWR キャッシュ、JSON ファーストの検索パラメーター、ファイルベースのルート生成、エンドツーエンドの型推論を組み込んだ、React および Solid 向けの型安全なルーターです。コアはフレームワークに依存せず、React と Solid のバインディングがその上に重ねられています。

CRITICAL: TanStack Router の型は完全に推論されます。キャストも、推論された値への型注釈も行わないでください。これは AI エージェントが最もよく犯す間違いです。

CRITICAL: TanStack Router はクライアントファーストです。ローダーはデフォルトでクライアント上で実行され、Remix／Next.js のようにサーバー専用ではありません。TanStack Router の API を Next.js や React Router の API と混同しないでください。

このエントリースキルを使って、主要なサブスキルを1つ選んでください。カタログ全体を読み込まないでください。認証が必要なローダーのように、実際に境界をまたぐタスクの場合に限り、2つ目のサブスキルを読み込んでください。その場合は auth-and-guards と data-loading の両方が必要です。

サブスキル

タスク	サブスキル
検索パラメーターの検証、読み取り、書き込み、変換	router-core/search-params/SKILL.md
動的セグメント、スプラット、オプションパラメーター	router-core/path-params/SKILL.md
Link、useNavigate、プリロード、ブロック	router-core/navigation/SKILL.md
ルートローダー、SWR キャッシュ、コンテキスト、遅延データ	router-core/data-loading/SKILL.md
認証ガード、RBAC、beforeLoad によるリダイレクト	router-core/auth-and-guards/SKILL.md
自動および手動のコード分割	router-core/code-splitting/SKILL.md
404 の処理、エラーバウンダリー、notFound()	router-core/not-found-and-errors/SKILL.md
推論、Register、from の絞り込み、TS のパフォーマンス	router-core/type-safety/SKILL.md
ストリーミング／非ストリーミング SSR、ハイドレーション、head 管理	router-core/ssr/SKILL.md

クイック判断ツリー

Need to add/read/write URL query parameters?
  → router-core/search-params

Need dynamic URL segments like /posts/$postId?
  → router-core/path-params

Need to create links or navigate programmatically?
  → router-core/navigation

Need to fetch data for a route?
  Is it client-side only or client+server?
    → router-core/data-loading
  Using TanStack Query as external cache?
    → compositions/router-query (separate skill)

Need to protect routes behind auth?
  → router-core/auth-and-guards

Need to reduce bundle size per route?
  → router-core/code-splitting

Need custom 404 or error handling?
  → router-core/not-found-and-errors

Having TypeScript issues or performance problems?
  → router-core/type-safety

Need server-side rendering?
  → router-core/ssr

複数の領域にまたがる完了チェック

ルートのリファクタリングの場合：

1. ルートファイルの名前を変更するか移動してください。生成された createFileRoute のパスを手動で編集しないでください。
2. 設定済みの Router プラグインまたは CLI を使って routeTree.gen.ts を再生成してください。
3. 古いルートを参照するリンク、リダイレクト、from の絞り込み、パラメーター、テストを更新してください。
4. 型テストと本番ビルドを実行してください。型チェックだけでは、ルートの生成やバンドルが機能することを確認できません。

レスポンススキーマを変更する場合：

1. ソースモデルと共有の検証スキーマを更新してください。
2. サーバー関数または API シリアライザーを更新し、実行時にフィールドが存在するようにしてください。
3. キャストせずに、ローダーとコンポーネントの利用箇所を更新してください。
4. 単体テストまたは統合テストで、実際のレスポンスペイロードを検証してください。型チェックでは、新しいフィールドをシリアライザーが出力し忘れていても検出できません。

最小限の動作例

// src/routes/__root.tsx
import { createRootRoute, Outlet } from '@tanstack/react-router'

export const Route = createRootRoute({
  component: () => <Outlet />,
})

// src/routes/index.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/')({
  component: () => <h1>Home</h1>,
})

// src/router.tsx
import { createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'

const router = createRouter({ routeTree })

// REQUIRED for type safety — without this, Link/useNavigate have no autocomplete
declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}

export default router

// src/main.tsx
import { RouterProvider } from '@tanstack/react-router'
import router from './router'

function App() {
  return <RouterProvider router={router} />
}

よくある間違い

重大：createFileRoute のパス文字列はファイルパスと一致させる必要があります

Vite プラグインが createFileRoute のパス文字列を管理します。手動で変更しないでください。src/routes/ 配下のファイルの場所と一致させる必要があります。

// File: src/routes/posts/$postId.tsx
export const Route = createFileRoute('/posts/$postId')({
  // ✅ matches file path
  component: PostPage,
})

export const Route = createFileRoute('/post/$postId')({
  // ❌ silent mismatch
  component: PostPage,
})

この文字列はプラグインが自動生成します。ルートファイルの名前を変更すると、プラグインが文字列を更新します。パス文字列を手動で編集しないでください。

バージョンに関する注意

このスキルの対象は @tanstack/router-core v1.171.15 です。スプラットルートには $ を使用します（* ではありません）。互換性のための * エイリアスは v2 で削除されます。