Vue Router

Common errors

• Uncaught (in promise) NavigationDuplicated: Avoided redundant navigation to current location

  cause Attempting to navigate to the same route (path and parameters) that the application is currently on, often triggered by `router.push()` or `RouterLink` clicks.
  fix 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.

• No match for current location: "/some/invalid/path"

  cause The URL in the browser does not match any defined route in your `routes` array. This often happens with incorrect paths, typos, or missing catch-all routes.
  fix 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.

• Error: "[Vue Router warn]: Router must be installed explicitly using `app.use(router)`"

  cause The Vue Router instance was created but not registered with the Vue application instance using `app.use()`.
  fix 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');`.

• Property '$route' does not exist on type '...' or 'Property '$router' does not exist on type '...'

  cause TypeScript error indicating that the `$route` or `$router` properties are not recognized within a component. This often occurs in `<script setup>` contexts or when types are not correctly inferred/augmented.
  fix 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)`.

Warnings

• breaking In Vue Router v5.0.3, experimental features `miss()` now throws internally and returns `never`, instead of returning an error instance. Additionally, `reroute()` was added, and `NavigationResult` has been deprecated, with `selectNavigationResult` being removed.
  Fix: Replace `throw miss()` with just `miss()` if you were explicitly throwing it. Adapt to `reroute()` instead of `NavigationResult` and remove usages of `selectNavigationResult`.
• breaking For developers migrating from `unplugin-vue-router` to Vue Router 5, import paths for the Vite plugin, data loaders, utility imports, and Volar plugins have changed.
  Fix: 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.
• breaking The IIFE (Immediately Invoked Function Expression) build of Vue Router 5 no longer includes `@vue/devtools-api` because it has been upgraded to v8 and does not expose an IIFE build itself.
  Fix: 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.
• breaking In an experimental breaking change from v5.0.0-beta.1, query parameters are now optional by default. This might alter how routes with optional query parameters are matched or handled.
  Fix: 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.
• deprecated The `next()` callback with a string argument in navigation guards (e.g., `next('/path')`) has a deprecation warning in v5.0.3. It's recommended to use `next({ path: '/path' })` or `return '/path'` for better consistency and type safety.
  Fix: 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()`.
• gotcha When using `createWebHistory`, server configuration is required to handle direct access to deep links (e.g., refreshing a non-root page). Without it, the server might return a 404 error.
  Fix: 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.

Install

• npm install vue-router npm
• yarn add vue-router yarn
• pnpm add vue-router pnpm

Imports

• createRouter
  wrong:

  import VueRouter from 'vue-router'

  correct:

  import { createRouter } from 'vue-router'

  Named export for creating a router instance. Vue Router 3 (for Vue 2) used a default export or `new VueRouter()`.
• createWebHistory
  wrong:

  import { createHistory } from 'vue-router'

  correct:

  import { createWebHistory } from 'vue-router'

  Used to configure HTML5 history mode (pushState API). Other history modes like `createWebHashHistory` or `createMemoryHistory` are also available.
• RouterView

  import { RouterView } from 'vue-router'

  The component used to display the component matched by the current route. It's globally registered by default, but can be imported locally for explicit usage or type inference.
• useRouter

  import { useRouter } from 'vue-router'

  Composition API hook to access the router instance within a component. For Options API, use `this.$router`.
• RouteLocationRaw

  import type { RouteLocationRaw } from 'vue-router'

  Type import for route locations, useful for type-checking navigation calls (`router.push`) and `RouterLink` `to` prop.

Quickstart

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.

import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import App from './App.vue'

// 1. Define route components.
const Home = { template: '<div>Home Page</div>' }
const About = { template: '<div>About Page</div>' }
const User = { 
  template: `
    <div>
      User {{ $route.params.id }}
      <RouterLink :to="'/user/' + ($route.params.id as any) + '/profile'">Profile</RouterLink>
      <RouterLink :to="'/user/' + ($route.params.id as any) + '/posts'">Posts</RouterLink>
      <RouterView />
    </div>
  ` 
}
const UserProfile = { template: '<div>User Profile</div>' }
const UserPosts = { template: '<div>User Posts</div>' }
const NotFound = { template: '<div>404 Not Found</div>' }

// 2. Define some routes
// Each route should map to a component.
const routes = [
  { path: '/', component: Home },
  { path: '/about', component: About },
  { 
    path: '/user/:id',
    component: User,
    children: [
      { path: 'profile', component: UserProfile },
      { path: 'posts', component: UserPosts },
    ]
  },
  { path: '/:pathMatch(.*)*', name: 'NotFound', component: NotFound },
]

// 3. Create the router instance and pass the `routes` option
const router = createRouter({
  // 4. Provide the history implementation to use.
  history: createWebHistory(process.env.BASE_URL ?? '/'),
  routes, // short for `routes: routes`
})

// 5. Create and mount the root instance.
const app = createApp(App)
app.use(router)

app.mount('#app')

/* In your App.vue template: */
// <template>
//   <h1>Hello Vue Router!</h1>
//   <nav>
//     <RouterLink to="/">Go to Home</RouterLink>
//     <RouterLink to="/about">Go to About</RouterLink>
//     <RouterLink to="/user/123">Go to User 123</RouterLink>
//     <RouterLink to="/non-existent">Go to 404</RouterLink>
//   </nav>
//   <main>
//     <RouterView />
//   </main>
// </template>

// <script setup lang="ts">
// import { RouterLink, RouterView } from 'vue-router'
// </script>