Vue Router is the official client-side routing library for Vue.js, providing robust and declarative navigation for single-page applications. The current stable version is 5.0.4, primarily designed for Vue 3 projects. It generally follows a regular release cadence, with minor bug fixes and experimental features being integrated frequently, and major versions released less often but incorporating significant architectural changes or merges. A key differentiator of Vue Router 5 is the integration of `unplugin-vue-router` into its core, enabling file-system based routing and simplifying route definition by convention. This merge aims to streamline development workflows, reducing boilerplate compared to earlier versions and offering a more integrated experience for large-scale applications. It also provides strong TypeScript support out of the box, ensuring type safety for route definitions and navigation guards.
npm install vue-routerVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates the basic setup of Vue Router 5 with Vue 3, including route definitions, history mode, `RouterLink`, and `RouterView` components, and a catch-all 404 route.
Replace `throw miss()` with just `miss()` if you were explicitly throwing it. Adapt to `reroute()` instead of `NavigationResult` and remove usages of `selectNavigationResult`.
Update imports: `unplugin-vue-router/vite` to `vue-router/vite`, `unplugin-vue-router/data-loaders/*` to `vue-router/experimental`, `unplugin-vue-router` to `vue-router/unplugin`, and Volar plugins from `unplugin-vue-router/volar/*` to `vue-router/volar/*`. Remove `unplugin-vue-router` dependency.
If relying on the `@vue/devtools-api` in an IIFE context, you may need to include it separately or adjust your build process. This primarily affects projects using the IIFE build directly for browser environments.
Review routes and navigation logic that rely on the presence of query parameters. Explicitly mark them as required if their absence should lead to a different route match or behavior.
Update navigation guards to use `next({ path: '/path' })` or `return { path: '/path' }` for programmatic navigation, or `return '/path'` for simpler redirects. Avoid passing string arguments directly to `next()`.Configure your web server (e.g., Nginx, Apache, or Node.js server) to redirect all unmatched paths to your `index.html` file. This allows Vue Router to take over client-side routing.
Catch the promise returned by `router.push()` or `router.replace()` to handle navigation failures gracefully: `router.push(...).catch(err => { if (isNavigationFailure(err, NavigationFailureType.duplicated)) console.log('Duplicate navigation'); })`. Alternatively, ensure your navigation logic only triggers when the target route is different.Ensure all intended paths are explicitly defined in your router's `routes` configuration. For unhandled paths, add a catch-all route (e.g., `{ path: '/:pathMatch(.*)*', name: 'NotFound', component: NotFoundComponent }`) as the last entry in your `routes` array to render a 404 page.After creating your `router` instance with `createRouter()`, make sure to call `app.use(router)` on your Vue application instance before mounting it: `const app = createApp(App); app.use(router); app.mount('#app');`.For Composition API (`<script setup>`), use `useRoute()` and `useRouter()` hooks directly: `const route = useRoute(); const router = useRouter();`. For Options API, ensure your `tsconfig.json` correctly includes `vue-router/client` types and that global properties are properly augmented if necessary, though `this.$route` and `this.$router` usually work out of the box with `app.use(router)`.