tanstack-vue-router-skilld

@tanstack/vue-router

Vue 用の型安全なルーターです。準備済みソース：バージョン 1.170.35（package.json:3）。

• vue >= 3.3.0（peer）および Node >= 20.19 が必要です（package.json:59-88）
• ランタイム依存関係：@tanstack/[email protected]、@tanstack/[email protected]、@tanstack/vue-store@^0.11.0
• ESM のみ（"type": "module"）。main／CJS エントリーポイントはありません
• エントリーポイント：@tanstack/vue-router、@tanstack/vue-router/ssr/server、@tanstack/vue-router/ssr/client（package.json:29-50）

ドキュメント：https://tanstack.com/router（フレームワークのページは /router/latest/docs/framework/vue/... で確認済み）

重要なルール

1. ほとんどのコンポーザブルは Ref<T> を返します — スクリプト内では .value を使用し、テンプレートでは自動的にアンラップされます。useRouter()、useNavigate()、useLinkProps()、useAwaited() は ref を返しません。完全な一覧は references/composables.md を参照してください。
2. 推論されるルート／ルーターの型をキャストしたり、注釈を付けたりしないでください。 型はルートツリーと Register 宣言から取得されます。
3. 型安全性のためにルーターを登録してください — 登録しないと、Link／useNavigate／useSearch は任意の文字列を受け入れます：

declare module '@tanstack/vue-router' {
  interface Register {
    router: typeof router
  }
}

4. vue-router ではありません。 vue-router から useRoute／useRouter をインポートしないでください。また、<router-view>／<router-link> も使用しないでください。
5. beforeLoad／loader は通常の非同期関数です。 Vue のコンポーザブル（ref、computed、ライフサイクルフック）はその中で実行できません。ルーターの context を通じて状態を渡してください。
6. ルートオプションでは Vue SFC を使用できます。component、errorComponent、notFoundComponent、pendingComponent と、ルーターオプションの default*Component は、.vue ファイルまたは h() 形式の関数コンポーネントを受け取ります（src/route.ts:54-58、src/router.ts:26-65）。

Vite を使ったセットアップ（ファイルベースルーティング）

npm install @tanstack/vue-router
npm install -D @tanstack/router-plugin @vitejs/plugin-vue @vitejs/plugin-vue-jsx

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import vueJsx from '@vitejs/plugin-vue-jsx'
import { tanstackRouter } from '@tanstack/router-plugin/vite'

export default defineConfig({
  plugins: [
    tanstackRouter({ target: 'vue', autoCodeSplitting: true }), // before vue()
    vue(),
    vueJsx(), // needed for .tsx route files
  ],
})

出典：公式 Vue の例、https://github.com/TanStack/router/blob/main/examples/vue/basic-file-based-sfc/vite.config.ts

// src/main.ts
import { createApp, h } from 'vue'
import { RouterProvider, createRouter } from '@tanstack/vue-router'
import { routeTree } from './routeTree.gen'

const router = createRouter({
  routeTree,
  defaultPreload: 'intent',
  scrollRestoration: true,
})

declare module '@tanstack/vue-router' {
  interface Register {
    router: typeof router
  }
}

createApp({ setup: () => () => h(RouterProvider, { router }) }).mount('#app')

ファイル名、分割ファイルの規則（.route.ts、.component.vue、.lazy.ts）、生成される routeTree.gen.ts については、references/file-based-routing.md を参照してください。

コードベースのルーティング

import { h } from 'vue'
import { createRootRouteWithContext, createRoute, createRouter, Outlet } from '@tanstack/vue-router'

interface RouterContext { auth: { isAuthenticated: boolean } }

const rootRoute = createRootRouteWithContext<RouterContext>()({ component: () => h(Outlet) })

const postsRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: 'posts',
  loader: ({ context }) => fetchPosts(context.auth),
})

const routeTree = rootRoute.addChildren([postsRoute])
const router = createRouter({
  routeTree,
  context: { auth: { isAuthenticated: false } },
})

ルートオプション、ルートオブジェクト上のフック、プロパティの順序に関するルールについては、references/routes.md を参照してください。

コンポーザブル

コンポーザブル	戻り値	備考
useRouter()	router instance	ref ではありません
useRouterState({ select })	Ref<T>	再レンダリングを避けるために select を渡します
useNavigate({ from? })	function	ref ではありません
useSearch({ from })	Ref<T>	from が一致しない場合はエラーになります
useParams({ from })	Ref<T>
useMatch({ from })	Ref<T>
useLoaderData({ from })	Ref<T>
useLoaderDeps({ from })	Ref<T>
useRouteContext({ from })	Ref<T>
useLocation()	Ref<ParsedLocation>
useMatches() / useParentMatches() / useChildMatches()	Ref<Array<Match>>	select を受け取ります
useMatchRoute()	function	呼び出すと Ref<false | params> を返します（src/Matches.tsx:148-172）
useLinkProps(options)	link props object	カスタムアンカー向け
useBlocker({ shouldBlockFn })	void または Ref<BlockerResolver>	リゾルバーが返されるのは withResolver: true の場合のみです
useCanGoBack()	Ref<boolean>	location.state.__TSR_index !== 0（src/useCanGoBack.ts:4-10）
useAwaited({ promise })	[data, promise] tuple	遅延データ向け

ルートオブジェクトと getRouteApi('/path') は、同じフックをスコープ済みの状態で公開します：Route.useSearch()、Route.useLoaderData()、Route.useNavigate()、Route.Link（src/route.ts:72-80）。

詳細と select／strict の動作については、references/composables.md を参照してください。

コンポーネント

コンポーネント	目的
<RouterProvider :router="router" />	ルーターをマウントします。追加の属性でルーターのオプションを更新します（src/RouterProvider.tsx:60-95）
<Link to="..." :params="..." :search="...">	型安全なアンカーです。有効状態では data-status="active" と aria-current="page" が設定されます（src/link.tsx:522-525）。デフォルトスロットには { isActive } が渡されます（src/link.tsx:918）
<Outlet />	一致した子ルートをレンダリングします（src/Match.tsx:275）
<Navigate to="..." />	宣言的なリダイレクトです。onMounted で実行されます（src/useNavigate.tsx:24-40）
<MatchRoute to="..." :fuzzy="true">	一致した場合にスロットをレンダリングします。スコープ付きスロットにはパラメーターが渡されます
<Await :promise="p">	<Suspense> を使った遅延データです（src/awaited.tsx:26-43）
<Block :should-block-fn="fn">	ナビゲーションをブロックします。スコープ付きスロットにはリゾルバーが渡されます（src/useBlocker.tsx:470-491）
<CatchBoundary> / <ErrorComponent>	onErrorCaptured によるエラーバウンダリーです
<ClientOnly>	マウント後にのみ子要素をレンダリングします
<HeadContent>, <Scripts>, <Html>, <Body>, <Asset>, <ScriptOnce>	SSR ドキュメントシェル

リンクのオプション、activeProps（デフォルトは { class: 'active' }、src/link.tsx:477）、プリロード（intent/viewport/render）、linkOptions()、createLink()については、references/navigation-links.mdを参照してください。

データの読み込みとリダイレクト

const route = createFileRoute('/posts/$postId')({
  beforeLoad: async ({ context, params }) => {
    if (!context.auth.isAuthenticated) {
      throw redirect({ to: '/login', search: { from: params.postId } })
    }
  },
  loaderDeps: ({ search: { page } }) => ({ page }),
  loader: ({ deps, params }) => fetchPost(params.postId, deps.page),
  pendingComponent: PendingSpinner, // .vue file works too
})

throw redirect()、isRedirect()、defer() による遅延ストリーミング、コンテキストの型付けについては、references/data-loading.mdを参照してください。

検索パラメーター

import { z } from 'zod' // or plain validators
const route = createFileRoute('/posts')({
  validateSearch: z.object({ page: z.number().default(1) }),
  search: {
    middlewares: [stripSearchParams({ page: 1 })],
  },
})

バリデーター、入力／出力スキーマ、retainSearchParams/stripSearchParams、カスタムシリアライズについては、references/search-params.mdを参照してください。

1.170.x での非推奨項目（代わりに使用）

非推奨	置き換え	根拠
Route、RootRoute、FileRoute、RouteApi クラス	createRoute、createRootRoute、createFileRoute、getRouteApi	src/route.ts:95、src/route.ts:220、src/route.ts:460、src/fileRoute.ts:57
rootRouteWithContext	createRootRouteWithContext	src/route.ts:414
NotFoundRoute / routerOptions.notFoundRoute	notFoundComponent ルートオプション / defaultNotFoundComponent ルーターオプション	https://tanstack.com/router/latest/docs/framework/vue/guide/not-found-errors
<ScrollRestoration />	createRouter の scrollRestoration: true	src/ScrollRestoration.tsx:18
beforeLoad/loader の opts.navigate	throw redirect({ to })	https://tanstack.com/router/latest/docs/framework/vue/api/router/RouteOptionsType
parseParams/stringifyParams	params.parse/params.stringify	同じ RouteOptionsType ドキュメント
preSearchFilters/postSearchFilters	search.middlewares	同じ RouteOptionsType ドキュメント
FileRouteLoader / 個別の .lazy.ts ローダーファイル	ローダーをルートファイル内に記述する	src/fileRoute.ts:153
useBlocker(fn, condition) の旧シグネチャ	{ shouldBlockFn } オブジェクト	src/useBlocker.tsx:139-151

ベストプラクティス

• ルーターで defaultPreload: 'intent' を設定します。プリロードされたデータはキャッシュされます（デフォルトは 30 s、defaultPreloadMaxAge）— https://tanstack.com/router/latest/docs/framework/vue/guide/preloading
• loaderDeps では、ローダーが使用する検索パラメーターのみを選択します。search をすべて展開すると、無関係なパラメーターが変更されるたびにローダーが再実行されます — https://tanstack.com/router/latest/docs/framework/vue/guide/data-loading
• 深い階層のコンポーネントでは、Route オブジェクトをインポートする代わりに getRouteApi('/posts/$postId') を使用します（循環インポートを回避できます）— https://tanstack.com/router/latest/docs/framework/vue/guide/data-loading
• beforeLoad のエラーハンドラーから再スローする場合は、リダイレクトが握りつぶされないよう、最初に isRedirect(error) を確認します — https://tanstack.com/router/latest/docs/framework/vue/guide/authenticated-routes
• ルートオプションの順序は型推論に影響します（loaderDeps より前に validateSearch／params、loader より前に beforeLoad）。create-route-property-order ESLint ルールは自動修正できます — https://tanstack.com/router/latest/docs/framework/vue/eslint/create-route-property-order
• 再利用可能なナビゲーション先には、単純なオブジェクトリテラルより linkOptions({ to, ... }) を優先します。<Link>、navigate()、redirect() で使用できます — https://tanstack.com/router/latest/docs/framework/vue/guide/link-options
• フックで select が新しいオブジェクトを返す場合は、ルーターで defaultStructuralSharing: true を有効にします — https://tanstack.com/router/latest/docs/framework/vue/guide/render-optimizations
• protocolAllowlist（デフォルトは DEFAULT_PROTOCOL_ALLOWLIST）に含まれないプロトコルを使用する外部リンクは、XSS を防ぐためにブロックされます（src/link.tsx:543-550）

参考資料

• references/api-surface.md — すべての公開エクスポートを分類して掲載
• references/composables.md — フックのシグネチャと Ref のセマンティクス
• references/routes.md — ルートの作成、オプション、ルートフック
• references/navigation-links.md — Link、ナビゲーション、ブロック、プリロード
• references/data-loading.md — ローダー、コンテキスト、リダイレクト、遅延データ
• references/search-params.md — バリデーションとミドルウェア
• references/file-based-routing.md — Vite プラグイン、命名、コード分割
• references/ssr.md — サーバーのエントリーポイントとドキュメントシェルコンポーネント