vue-router-skilld

vuejs/router [email protected]

準備したソース：[email protected]、ESM パッケージ（"type": "module"、package.json:2,20）。 Peer 依存関係：vue ^3.5.34 || ^4.0.0；オプションの依存関係：vite ^7.3.0 || ^8.0.0、pinia ^3.0.4 || ^4.0.2、@pinia/colada >=0.21.2（package.json:173-193）。 ドキュメント：https://router.vuejs.org

インポートマップ

インポート	用途
vue-router	createRouter、createWebHistory、createWebHashHistory、createMemoryHistory、RouterLink、RouterView、useRouter、useRoute、useLink、onBeforeRouteLeave、onBeforeRouteUpdate、isNavigationFailure、NavigationFailureType、START_LOCATION、parseQuery、stringifyQuery（dist/vue-router.d.ts:6）
vue-router/vite	Vite プラグイン、ファイルベースルーティング（package.json:104）
vue-router/unplugin/{vite,webpack,rollup,esbuild,rolldown}	他のバンドラー向けの同じプラグイン（dist/unplugin/）
vue-router/unplugin	VueRouterAutoImports、createRoutesContext、EditableTreeNode、プラグインの Options（dist/unplugin/index.d.mts:62）
vue-router/auto-routes	生成された routes 配列と handleHotUpdate(router)（vue-router-auto-routes.d.mts:6,28）
vue-router/auto-resolver	experimental_createRouter 用に生成された resolver と handleHotUpdate（vue-router-auto-resolver.d.mts:15,21）
vue-router/experimental	データローダー、reroute、miss、definePage、defineParamParser、PARAM_PARSER_INT/PARAM_PARSER_BOOL、experimental_createRouter、useIsDataLoading（dist/experimental/index.d.ts:7）
vue-router/experimental/pinia-colada	defineColadaLoader（package.json:77）
vue-router/volar/sfc-route-blocks、vue-router/volar/sfc-typed-router	Volar プラグイン：<route> ブロック、ファイルごとの型付き useRoute()（package.json:115-121）

避けるもの：

• vue-router/auto — 非推奨で、削除される予定です（vue-router-auto.d.ts:1）。
• CJS ビルドでの vue-router/experimental — v5.1.0 以降は ESM 専用です（https://github.com/vuejs/router/releases/tag/v5.1.0）。

クイックスタート（従来のルート）

import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  history: createWebHistory(),
  routes: [
    { path: '/', component: () => import('./pages/Home.vue') },
    { path: '/users/:id', component: () => import('./pages/User.vue'), props: true },
  ],
})
app.use(router)

コンポーネントでは、vue-router から useRoute() / useRouter() を使用します。<RouterLink to="..."> と <RouterView> は、app.use(router) によってグローバル登録されます。

クイックスタート（ファイルベースルーティング）

// vite.config.ts
import VueRouter from 'vue-router/vite'
import Vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [VueRouter(), Vue()], // Vue plugin MUST come after VueRouter
})

import { createRouter, createWebHistory } from 'vue-router'
import { routes, handleHotUpdate } from 'vue-router/auto-routes'

const router = createRouter({ history: createWebHistory(), routes })
if (import.meta.hot) handleHotUpdate(router)

デフォルトでは、ページは src/pages に配置します。開発サーバーを一度起動して typed-router.d.ts を生成し、"moduleResolution": "Bundler" を指定して tsconfig.json の include に追加します。詳細、命名規則、プラグインのオプションについては、references/file-based-routing.md を参照してください。

コアのルール

• ナビゲーションガードでは値を返し、next() は呼び出さないでください。next は非推奨であり（v5.0.3 以降、実行時に警告が表示されます）、削除される予定です（dist/index-D7ja2BKs.d.ts:362-393, https://github.com/vuejs/router/releases/tag/v5.0.3）。

  router.beforeEach(to => {
    if (to.meta.requiresAuth && !isAuthenticated) return { name: 'login' }
    // return nothing, true, false, or a route location
  })
  

• データローダーでは、reroute(to) でリダイレクトしてください。new NavigationResult(to) は非推奨で、警告が記録されます（dist/experimental/index.js:1106-1111）。
• router.currentRoute は ShallowRef<RouteLocationNormalizedLoaded> です。router.currentRoute.value として読み取ってください（dist/index-D7ja2BKs.d.ts:1433）。
• router.onReady() は存在しません（v4 で削除されました）。await router.isReady() を使用してください。
• scrollBehavior は { top, left } を返します（v4 で x／y が left／top に変更されました）。
• ナビゲーションの失敗を検出するには、const failure = await router.push(...) とし、isNavigationFailure(failure, NavigationFailureType.aborted) で確認してください。
• route.meta は、一致したすべてのレコードから非再帰的にマージされます。to.matched を走査するのではなく、to.meta.requiresAuth を直接読み取ってください。RouteMeta のモジュール拡張を使って meta の型を指定してください。
• 非同期コンポーネントの解決が必要な処理には、beforeEach ではなく router.beforeResolve を使用してください。
• Pinia ストアにアクセスするには、ガード内で inject() を使用してください（Vue 3.3 以降でサポートされています）。
• props: true または props: route => ({ ... }) でコンポーネントをルーターから切り離してください。コンポーネントをテスト可能に保つため、クエリ値もこの方法で渡してください。
• 狭い対象を監視してください（() => route.params.id など）。route オブジェクト全体は監視しないでください。

コア API に関する注記の全容：references/core-api.md。

型付きルート

ファイルベースのルーティングプラグインを使用すると有効になります（型は自動生成されます）。または、手動で拡張してください。

declare module 'vue-router' {
  interface TypesConfig {
    RouteNamedMap: RouteNamedMap
  }
}

型付きの push('/users/:id', { params: { id: 42 } })、型付きの useRoute()、Volar プラグイン vue-router/volar/sfc-typed-router によるファイルごとの型指定が利用できます。パラメーターパーサー（int、bool、src/params/ 内のカスタムパーサー）を使うと、型付きで検証済みのパラメーターを利用できます。definePage({ params: { query: { page: { parser: 'int', default: 1 } } } }) でクエリパラメーターを宣言できます。詳細：references/typed-routes.md。

データローダー（実験的）

// src/pages/users/[id].vue
import { defineBasicLoader } from 'vue-router/experimental'
import { reroute } from 'vue-router/experimental'

export const useUserData = defineBasicLoader(async (to) => {
  if (!to.params.id) reroute('/') // reroute throws: stops the loader immediately
  return fetchUser(to.params.id)
})

ルーターより前に DataLoaderPlugin をインストールしてください：app.use(DataLoaderPlugin, { router })。非ブロッキングローダーを使うには、defineBasicLoader(loader, { lazy: true }) とします。この場合、エラーは router.onError ではなく error に格納されます。詳細：references/data-loaders.md。

バージョンに関する注記（5.0.x → 5.3.1）

• v5.0.7：RouteNamedMap が生成された typed-router.d.ts を通じて接続されました（https://github.com/vuejs/router/releases/tag/v5.0.7）。パラメーターパーサーのフォルダーに include／exclude が追加されました。
• v5.1.0：型付き definePage の params.path、defineParamParserRaw、厳密なデフォルト型指定、TypesConfig によるグローバルな Router のオーバーライドが追加されました。実験的なエクスポートは ESM のみになりました（https://github.com/vuejs/router/releases/tag/v5.1.0）。
• v5.2.0：よくある間違いに対する診断機能が追加されました。pinia 4 が利用可能になりました（https://github.com/vuejs/router/releases/tag/v5.2.0）。
• v5.3.0：history.scrollRestoration の設定に応じてスクロールをスキップするようになりました。重複した definePage() はクラッシュせずに報告されるようになりました。EditableTreeNode.name に false を指定して解除できるようになりました（https://github.com/vuejs/router/releases/tag/v5.3.0）。
• v5.3.1：文字列以外のパラメーターを指定した場合の isActive の問題が修正されました（https://github.com/vuejs/router/releases/tag/v5.3.1）。

v3／v4 からの移行、または unplugin-vue-router からの移行：references/migration.md。

参考資料

• core-api.md — ルーターの作成、履歴、ガード、失敗、スクロール、RouterLink/RouterView。
• file-based-routing.md — プラグインのセットアップ、ファイル名、definePage、<route> ブロック、extendRoute、オプション。
• typed-routes.md — TypesConfig、生成される型、パラメーターのパーサー、experimental_createRouter。
• data-loaders.md — defineBasicLoader、defineColadaLoader、reroute、遅延ローダー、SSR に関する注意事項。
• migration.md — v3→v4 および v4→v5 の変更点、v5 系の非推奨項目。