Experimental Router

WARNING

The experimental router reflects the explorations of the upcoming major version of Vue Router. It is not production-ready and should be used for testing and feedback purposes only.

The experimental router introduces a new resolver-based matching layer that powers stronger typing, file-based routing, and custom param parsers.

Installation

The experimental router lives next to the stable one and is opt-in. You import the factory from vue-router/experimental and a resolver (from vue-router/auto-resolver when using file-based routing):

// src/router/index.ts
import { createWebHistory } from 'vue-router'
import { experimental_createRouter as createRouter } from 'vue-router/experimental'
import { resolver, handleHotUpdate } from 'vue-router/auto-resolver'

export const router = createRouter({
  history: createWebHistory(),
  resolver,
})

if (import.meta.hot) {
  handleHotUpdate(router)
}

Since the experimental router doesn't add the <RouterLink> and <RouterView> components, you need to register them globally:

// src/main.ts
import { createApp } from 'vue'
import { RouterLink, RouterView } from 'vue-router'
import App from './App.vue'
import { router } from './router'

const app = createApp(App)
app.component('RouterLink', RouterLink)
app.component('RouterView', RouterView)
app.use(router)
app.mount('#app')

Opt-in to typed useRouter() / useRoute()

To get a stricter router instance type from useRouter(), register your router on TypesConfig:

// src/main.ts
declare module 'vue-router' {
  export interface TypesConfig {
    Router: typeof router
  }
}

Query values are arrays

In the experimental router, every key in route.query has an array value. A key without a value gives [null], and a missing key is undefined:

// /search?q=vue&tag=a&tag=b&debug
route.query.q // ['vue']
route.query.tag // ['a', 'b']
route.query.debug // [null]
route.query.page // undefined

When you navigate, also pass arrays. A non array value still works, but it shows a deprecation warning in development:

router.push({ query: { q: ['vue'] } }) 
router.push({ query: { q: 'vue' } }) 

An empty array is the same as a missing key: { tag: [] } and {} give the same location.

Navigation and redirects

Relative string locations passed to router.push(), router.replace(), or router.resolve() use the current route as their base:

// Current route: /users/posva
router.push('add') // /users/add

Relative object locations need an explicit current location. Resolve them first, then navigate:

const target = router.resolve(
  { query: { page: ['2'] } },
  router.currentRoute.value
)
router.push(target)

Navigation guard redirects

Relative redirects returned by navigation guards use the target route (to) as their base. This also applies to initial navigation and back/forward navigation:

router.beforeEach(to => {
  if (to.path === '/users/posva') return 'add'
})
// Navigating to /users/posva redirects to /users/add.

An object redirect without a name or path keeps the target's params, query, and hash unless the redirect overrides them:

router.beforeEach(to => {
  if (to.path === '/search' && !to.query.page) {
    return { query: { page: ['2'] } }
  }
})
// /search?q=vue#results redirects to /search?q=vue&page=2#results.

Named redirects and absolute paths do not inherit params, query, or hash. Supply any required params when returning a named route.

Route record redirects

A route record's redirect must return a named location or an absolute path (starting with /). It does not inherit params, query, or hash from the navigation target or current route. Copy values from to when you need to keep them:

// In a page's definePage() call
definePage({
  redirect: to => ({
    path: '/search',
    query: to.query,
    hash: to.hash,
  }),
})

With Data Loaders

If you use Data Loaders, install the plugin before the router:

import { DataLoaderPlugin } from 'vue-router/experimental'

app.use(DataLoaderPlugin, { router })
app.use(router)