vue-router-skilld

vuejs/router

vue-router@5.3.1

Prepared source:

vue-router@5.3.1

, ESM package (

"type": "module"

, package.json:2,20). Peers:

vue ^3.5.34 || ^4.0.0

; optional

vite ^7.3.0 || ^8.0.0

pinia ^3.0.4 || ^4.0.2

@pinia/colada >=0.21.2

(package.json:173-193). Docs: https://router.vuejs.org

Import map

Import	Use for
`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 plugin, file-based routing (package.json:104)
`vue-router/unplugin/{vite,webpack,rollup,esbuild,rolldown}`	same plugin for other bundlers (dist/unplugin/)
`vue-router/unplugin`	`VueRouterAutoImports` , `createRoutesContext` , `EditableTreeNode` , plugin `Options` (dist/unplugin/index.d.mts:62)
`vue-router/auto-routes`	generated `routes` array + `handleHotUpdate(router)` (vue-router-auto-routes.d.mts:6,28)
`vue-router/auto-resolver`	generated `resolver` for `experimental_createRouter` + `handleHotUpdate` (vue-router-auto-resolver.d.mts:15,21)
`vue-router/experimental`	data loaders, `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 plugins: `<route>` blocks, per-file typed `useRoute()` (package.json:115-121)

Avoid:

```
vue-router/auto
```
— deprecated, will be removed (vue-router-auto.d.ts:1).
```
vue-router/experimental
```
in CJS builds — ESM-only since v5.1.0 (https://github.com/vuejs/router/releases/tag/v5.1.0).

Quick start (classic routes)

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)

In components:

useRoute()

useRouter()

from

vue-router

;

<RouterLink to="...">

and

<RouterView>

are globally registered by

app.use(router)

Quick start (file-based routing)

// 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)

Pages live in

src/pages

by default. Start the dev server once to generate

typed-router.d.ts

, add it to

tsconfig.json

include

with

"moduleResolution": "Bundler"

. Details, naming conventions, and plugin options: references/file-based-routing.md.

Core rules

Return values from navigation guards, never call
```
next()
```
.
```
next
```
is deprecated (runtime warning since v5.0.3) and will be removed (dist/index-D7ja2BKs.d.ts:362-393, https://github.com/vuejs/router/releases/tag/v5.0.3).
ts
```
router.beforeEach(to => {
  if (to.meta.requiresAuth && !isAuthenticated) return { name: 'login' }
  // return nothing, true, false, or a route location
})
```
In data loaders, redirect with
```
reroute(to)
```
;
```
new NavigationResult(to)
```
is deprecated and logs a warning (dist/experimental/index.js:1106-1111).

router.currentRoute

is a

ShallowRef<RouteLocationNormalizedLoaded>

— read it as

router.currentRoute.value

(dist/index-D7ja2BKs.d.ts:1433).

```
router.onReady()
```
does not exist (removed in v4); use
```
await router.isReady()
```
.
```
scrollBehavior
```
returns
```
{ top, left }
```
(v4 renamed
```
x
```
/
```
y
```
to
```
left
```
/
```
top
```
).

Detect failed navigations:

const failure = await router.push(...)

; check with

isNavigationFailure(failure, NavigationFailureType.aborted)

```
route.meta
```
merges non-recursively from all matched records; read
```
to.meta.requiresAuth
```
directly instead of scanning
```
to.matched
```
. Type
```
meta
```
via
```
RouteMeta
```
module augmentation.
Use
```
router.beforeResolve
```
(not
```
beforeEach
```
) for work that needs async components resolved.
Use
```
inject()
```
inside guards to reach Pinia stores (supported since Vue 3.3).
Decouple components from the router with route
```
props: true
```
or
```
props: route => ({ ... })
```
; pass query values this way to keep components testable.
Watch narrow sources (
```
() => route.params.id
```
), never the whole
```
route
```
object.

Full core API notes: references/core-api.md.

Typed routes

Enable by using the file-based routing plugin (types are generated automatically), or augment manually:

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

Typed

push('/users/:id', { params: { id: 42 } })

, typed

useRoute()

, per-file typing via Volar plugin

vue-router/volar/sfc-typed-router

. Param parsers (

int

bool

, custom in

src/params/

) give typed, validated params;

definePage({ params: { query: { page: { parser: 'int', default: 1 } } } })

declares query params. Details: references/typed-routes.md.

Data loaders (experimental)

// 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)
})

Install

DataLoaderPlugin

before the router:

app.use(DataLoaderPlugin, { router })

. Non-blocking loaders:

defineBasicLoader(loader, { lazy: true })

; errors then land in

error

, not in

router.onError

. Details: references/data-loaders.md.

Version notes (5.0.x → 5.3.1)

v5.0.7:
```
RouteNamedMap
```
is wired through the generated
```
typed-router.d.ts
```
(https://github.com/vuejs/router/releases/tag/v5.0.7); param parser folders gained
```
include
```
/
```
exclude
```
.
v5.1.0: typed
```
definePage
```
```
params.path
```
,
```
defineParamParserRaw
```
, strict default typing,
```
TypesConfig
```
global
```
Router
```
override, experimental export is ESM-only (https://github.com/vuejs/router/releases/tag/v5.1.0).
v5.2.0: added diagnostics for common mistakes; allows pinia 4 (https://github.com/vuejs/router/releases/tag/v5.2.0).
v5.3.0: scroll skips when
```
history.scrollRestoration
```
says so; duplicate
```
definePage()
```
reported instead of crashing;
```
EditableTreeNode.name
```
accepts
```
false
```
to unset (https://github.com/vuejs/router/releases/tag/v5.3.0).
v5.3.1: fixes
```
isActive
```
with non-string params (https://github.com/vuejs/router/releases/tag/v5.3.1).

Migration from v3/v4, or from

unplugin-vue-router

: references/migration.md.

References

core-api.md — router creation, histories, guards, failures, scroll, RouterLink/RouterView.
file-based-routing.md — plugin setup, file naming,
```
definePage
```
,
```
<route>
```
blocks,
```
extendRoute
```
, options.
typed-routes.md —
```
TypesConfig
```
, generated types, param parsers,
```
experimental_createRouter
```
.
data-loaders.md —
```
defineBasicLoader
```
,
```
defineColadaLoader
```
,
```
reroute
```
, lazy loaders, SSR notes.
migration.md — v3→v4 and v4→v5 changes, deprecations in the v5 line.

vue-router-skilld

NPX Install

Tags

SKILL.md Content

vuejs/router
`vue-router@5.3.1`