vue-router-skilld

What this skill does

# vuejs/router `[email protected]`
**Tags:** next: 4.0.13, legacy: 3.6.5, edge: 4.4.0-alpha.3

**References:** [Docs](./references/docs/_INDEX.md)
## API Changes

This section documents version-specific API changes — prioritize recent major/minor releases.

- NEW: `vue-router/vite` — v5 ships the Vite plugin (formerly `unplugin-vue-router/vite`) directly in the core package; import from `vue-router/vite` instead [source](./references/docs/guide/migration/v4-to-v5.md#2-update-imports)

- NEW: `vue-router/auto-routes` — v5 export that provides the auto-generated file-based route list; previously required `unplugin-vue-router` as a separate package [source](./references/docs/guide/migration/v4-to-v5.md#new-exports-reference)

- NEW: `vue-router/unplugin` — v5 export for Webpack/Rollup/esbuild plugins and utilities (`VueRouterAutoImports`, `EditableTreeNode`, `createRoutesContext`, etc.); previously imported from `unplugin-vue-router` [source](./references/docs/guide/migration/v4-to-v5.md#2-update-imports)

- NEW: `DataLoaderPlugin` + `defineBasicLoader` (experimental) — v5 adds data loaders directly to `vue-router/experimental`; previously in `unplugin-vue-router/data-loaders`. Install `DataLoaderPlugin` **before** the router with `app.use(DataLoaderPlugin, { router })` [source](./references/releases/v5.0.0.md#features)

- NEW: `defineColadaLoader` (experimental) — Pinia Colada-backed loader available at `vue-router/experimental/pinia-colada`; previously `unplugin-vue-router/data-loaders/pinia-colada` [source](./references/docs/guide/migration/v4-to-v5.md#2-update-imports)

- NEW: `NavigationResult` (experimental) — class from `vue-router/experimental` returned inside a loader to redirect during navigation (e.g. `return new NavigationResult('/login')`); previously did not exist in vue-router [source](./references/docs/data-loaders/defining-loaders.md#navigation-control)

- NEW: Volar plugins moved to `vue-router/volar/sfc-typed-router` and `vue-router/volar/sfc-route-blocks` — previously `unplugin-vue-router/volar/sfc-typed-router` and `unplugin-vue-router/volar/sfc-route-blocks` [source](./references/docs/guide/migration/v4-to-v5.md#2-update-imports)

- NEW: `TypesConfig` module augmentation — v4.4+ interface used to register `RouteNamedMap` for typed routes; augment with `declare module 'vue-router' { interface TypesConfig { RouteNamedMap: RouteNamedMap } }` [source](./references/docs/guide/advanced/typed-routes.md#manual-configuration)

- BREAKING: IIFE build no longer bundles `@vue/devtools-api` — v5 upgraded devtools-api to v8 which has no IIFE build; affects CDN/script-tag setups that relied on the bundled devtools [source](./references/releases/v5.0.0.md#v500)

- NEW: Query params optional by default (experimental) — v5 file-based routing makes query params optional in typed routes by default [source](./references/releases/v5.0.0.md#features)

**Also changed:** `unplugin-vue-router` types/utilities moved to `vue-router/unplugin` (renamed) · `route-map.d.ts` replaces `typed-router.d.ts` (renamed) · `meta.loaders` array on route records for manually connecting data loaders (NEW, experimental) · `router.currentRoute` is `Ref<RouteLocationNormalizedLoaded>` — access via `.value` (v4 BREAKING) · `router.onReady()` removed — use `router.isReady()` returning a Promise (v4 BREAKING) · `scrollBehavior` `x`/`y` renamed to `left`/`top` (v4 BREAKING)

## Best Practices

- Use `route.meta` directly in guards instead of iterating `to.matched` — Vue Router merges all ancestor `meta` fields non-recursively, so `to.meta.requiresAuth` already reflects inherited values from parent routes [source](./references/docs/guide/advanced/meta.md#typescript)

- Extend the `RouteMeta` interface via module augmentation to type all `meta` fields — this enforces that every route declares required fields at compile time rather than relying on runtime checks [source](./references/docs/guide/advanced/meta.md#typescript)

- Use `router.beforeResolve` (not `beforeEach`) for operations that must run after async components are resolved — it fires after all in-component guards and async route components are ready, making it the correct place for camera permission checks or final data validation [source](./references/docs/guide/advanced/navigation-guards.md#global-resolve-guards)

- Use `inject()` inside navigation guards (global or per-route) to access Pinia stores and provided values — this is supported since Vue 3.3 and avoids importing stores outside of `setup` context [source](./references/docs/guide/advanced/navigation-guards.md#global-injections-within-guards)

- Avoid the `next` callback in guards — return values (`false`, a route location, or nothing) instead; `next` is error-prone because it must be called exactly once per code path and is considered a legacy API [source](./references/docs/guide/advanced/navigation-guards.md#optional-third-argument-next)

- `await router.push()` and check the resolved value to detect navigation failures — the promise resolves to a `NavigationFailure` when blocked, or `undefined` on success; use `isNavigationFailure(result, NavigationFailureType.aborted)` to distinguish the specific failure type [source](./references/docs/guide/advanced/navigation-failures.md#detecting-navigation-failures)

- Set `props: true` (or a function) on route records to decouple components from `useRoute()` — components receiving params as props are reusable and testable without a router instance; use the function form (`props: route => ({ query: route.query.q })`) to map query params or cast types [source](./references/docs/guide/essentials/passing-props.md#function-mode)

- Watch specific `route` properties rather than the whole `route` object — `useRoute()` returns a reactive object, but watching it entirely triggers on any change (hash, query, params); narrow the watcher to `() => route.params.id` to avoid unnecessary fetches [source](./references/docs/guide/advanced/composition-api.md#accessing-the-router-and-current-route-inside-setup)

- (experimental) Use `defineBasicLoader` / `defineColadaLoader` exported from page components for navigation-aware data fetching — loaders exported from lazy-loaded route components are automatically connected to the navigation lifecycle, block the transition until resolved, and expose `isLoading`/`error` reactively; set `lazy: true` for non-critical data that should not block navigation [source](./references/docs/data-loaders/defining-loaders.md#non-blocking-loaders-with-lazy)