Migrating from Vue Router 0.7.x

Last update on August 19 2022 21:51:07 (UTC/GMT +8 hours)

The only Vue Router compatible with Vue 2 is the Vue Router 2, with this is mind, if you are updating Vue, you will also have to update Vue Router.

Router Initialization

router.start ^replaced

A special API to initialize an app with Vue Router no longer exists. What this means is that instead of:

router.start({
  template: '<router-view></router-view>'
}, '#app')

You can pass a router property to a Vue instance:

new Vue({
  el: '#app',
  router: router,
  template: '<router-view></router-view>'
})

Or, if you are using the runtime-only build of Vue:

new Vue({
  el: '#app',
  router: router,
  render: h => h('router-view')
})

Upgrade Path

To find examples of router.start being called, run the migration helper on your codebase.

Route Definitions

router.map ^replaced

We now define routes as an array on a routes option at router instantiation. So the routes below for example:

router.map({
  '/foo': {
    component: Foo
  },
  '/bar': {
    component: Bar
  }
})

Will be instead be defined as shown below:

var router = new VueRouter({
  routes: [
    { path: '/foo', component: Foo },
    { path: '/bar', component: Bar }
  ]
})

The array syntax allows route matching to be more predictable, since iterating over an object is not guaranteed to use the same property order across all browsers.

Upgrade Path

To find examples of router.map being called, run the migration helper on your codebase.

router.on^removed

If you need to generate routes programmatically when starting up your app, you can do that by dynamically pushing definitions to a routes array. For instance:

// your normal base routes
var routes = [
  // ...
]```
```// Dynamically generated routes
marketingPages.forEach(function (page) {
  routes.push({
    path: '/marketing/' + page.slug
    component: {
      extends: MarketingComponent
      data: function () {
        return { page: page }
      }
    }
  })
})

var router = new Router({
  routes: routes
})

If you need to add new routes after the router has been instantiated, you can replace the router's matcher with a new one that includes the route you'd like to add:

router.match = createMatcher(
  [{
    path: '/my/new/path',
    component: MyComponent
  }].concat(router.options.routes)
)

Upgrade Path

To find examples of router.on being called, run the migration helper on your codebase.

router.beforeEach^changed

The router.beforeEach now works asynchronously and takes a next function as its third argument.

router.beforeEach(function (transition) {
  if (transition.to.path === '/forbidden') {
    transition.abort()
  } else {
    transition.next()
  }
})
router.beforeEach(function (to, from, next) {
  if (to.path === '/forbidden') {
    next(false)
  } else {
    next()
  }
})

subRoutes^renamed

SubRoutes has been renamed to children for consistency within Vue and with other routing libraries.

Upgrade Path

To find examples of the subRoutes option, run the migration helper on your codebase.

router.redirect ^replaced

The router.redirect is now an option on route definitions. So for instance, you will have to update:

router.redirect({
  '/tos': '/terms-of-service'
})

to a definition like below in your routes configuration:

{
  path: '/tos',
  redirect: '/terms-of-service'
}

Upgrade Path

To find examples of router.redirect being called, run the migration helper on your codebase.

router.alias ^replaced

The router.alias is now an option on the definition for the route you'd like to alias to. So for instance, you will have to update:

router.alias({
  '/manage': '/admin'
})

to a definition like the one shown below in your routes configuration:

{
  path: '/admin',
  component: AdminPanel,
  alias: '/manage'
}

In cases where you need multiple aliases, you can use an array syntax as well:

alias: ['/manage', '/administer', '/administrate']

Upgrade Path

To find examples of router.alias being called, run the migration helper on your codebase.

Arbitrary Route Properties^replaced

Arbitrary route properties must be scoped under the new meta property now, so as to avoid conflicts with future features. So for instance, if you had previously defined:

'/admin': {
  component: AdminPanel,
  requiresAuth: true
}

Then you would now have to update it to:

{
  path: '/admin',
  component: AdminPanel,
  meta: {
    requiresAuth: true
  }
}

Then when accessing this property on a route later, you will still have go through meta. For instance:

if (route.meta.requiresAuth) {
  // ...
}

Upgrade Path

To find examples of arbitrary route properties not scoped under meta, run the migration helper on your codebase.

[] Syntax for Arrays in Queries^removed

When passing arrays to query parameters, the QueryString syntax is no longer /foo?users[]=Tom&users[]=Jerry, instead, the new syntax is /foo?users=Tom&users=Jerry is used. Internally, the $route.query.users will still be an Array, however, if there is only one parameter in the query: /foo?users=Tom, when we are directly accessing this route, there is no way for the router to know if we were expecting users to be an Array. Because of this, you should consider adding a computed property and then replacing every reference of $route.query.users with it:

export default {
  // ...
  computed: {
    // users will always be an array
    users () {
      const users = this.$route.query.users
      return Array.isArray(users) ? users : [users]
    }
  }
}

Route Matching

Route matching will now use path-to-regexp under the hood, hence making it much more flexible than previously.

One or More Named Parameters ^changed

The syntax has been changed slightly, so /category/*tags for instance, will have be updated to /category/:tags+.

Upgrade Path

To find examples of the obsolete route syntax, run the migration helper.

Links

v-link replaced

The v-link directive has been replaced by a new <router-link> component, as this sort of job is now solely the responsibility of components in Vue 2. That means whenever wherever you have a link like this:

<a v-link="'/about'">About</a>

You'll need to update it like this:

<router-link to="/about">About</router-link>

You should note that target="_blank" is not supported on <router-link>, so when you need to open a link in a new tab, you will have to use <a> instead.

Upgrade Path

To find examples of the v-link directive, you will have to run the migration helper on your codebase.

v-link-active^replaced

The v-link-active directive has also been replaced by the tag attribute on a <router-link> component. So for example, you will update this:

<li v-link-active>
  <a v-link="'/about'">About</a>
</li>

to:

<router-link tag="li" to="/about">
  <a>About</a>
</router-link>

In the case above, <a> will be the actual link (and will get the correct href), but the active class will be applied to the outer <li>.

Upgrade Path

Run the migration helper on your codebase to find examples of the v-link-active directive.

Programmatic Navigation

router.go^changed

For consistency with HTML5 History API, the router.go is now only used for back/forward navigation, while the router.push is used to navigate to a specific page.

Upgrade Path

To find examples of router.go being used where router.push should be used instead, run the migration helper.

Router Options: Modes

hashbang: false^removed

Hashbangs are not required for Google to crawl a URL anymore, so they are no more the default (or even an option) for the hash strategy.

Upgrade Path

To find examples of the hashbang: false option, run the migration helper on your codebase.

history: true^replaced

All the routing mode options have been condensed into a single mode option. Update:

var router = new VueRouter({
  history: 'true'
})

to:

var router = new VueRouter({
  mode: 'history'
})

Upgrade Path

To find examples of the history: true option, run the migration helper on your codebase.

abstract: true^replaced

All the routing mode options have been condensed into a single mode option. Update:

var router = new VueRouter({
  abstract: 'true'
})

to:

var router = new VueRouter({
  mode: 'abstract'
})

Upgrade Path

To find examples of the abstract: true option, run the migration helper on your codebase.

Route Options: Misc

saveScrollPosition^replaced

The saveScrollPosition has been replaced with a scrollBehavior option that accepts a function, such that the scroll behavior is completely customizable - even per route. This will open many new possibilities, but to replicate the old behavior of:

saveScrollPosition:^true

You can replace it with:

scrollBehavior: function (to, from, savedPosition) {
  return savedPosition || { x: 0, y: 0 }
}

Upgrade Path

To find examples of the saveScrollPosition: true option, run the migration helper on your codebase.

root^renamed

This has been renamed to base for consistency with the HTML <base> element.

Upgrade Path

To find examples of the root option, run the migration helper.

transitionOnLoad^removed

This option is no longer necessary now that Vue?s transition system has explicit appear transition control.

Upgrade Path

To find examples of the transitionOnLoad: true option, run the migration helper on your codebase.

suppressTransitionError^removed

The suppressTransitionError has been removed due to hooks simplification. If you really must suppress these transition errors, you can use try?catch if you prefer.

Upgrade Path

To find examples of the suppressTransitionError: true option, run the migration helper on your codebase.

Route Hooks

activate^replaced

You should use beforeRouteEnter in the component instead.

Upgrade Path

To find examples of the activate hook, run the migration helper on your codebase.

canActivate ^replaced

you should use beforeEnter in the route instead.

Upgrade Path

To find examples of the canActivate hook, run the migration helper on your codebase.

deactivate^removed

You should use the component?s beforeDestroy or destroyed hooks instead.

Upgrade Path

To find examples of the deactivate hook, run the migration helper.

canDeactivate^replaced

You should use beforeRouteLeave in the component instead.

Upgrade Path

To find examples of the canDeactivate hook, run the migration helper on your codebase.

canReuse: false^removed

There is no longer a use case for this in the new Vue Router.

Upgrade Path

To find examples of the canReuse: false option, run the migration helper on the codebase.

data^replaced

The $route property is reactive now, so you can use a watcher to react to route changes, like this:

watch: {
  '$route': 'fetchData'
},
methods: {
  fetchData: function () {
    // ...
  }
}

Upgrade Path

To find examples of the data hook, run the migration helper on your codebase.

$loadingRouteData^removed

You should define your own property (e.g. isLoading), then you update the loading state in a watcher on the route. For instance, if you are fetching data with axios:

data: function () {
  return {
    posts: [],
    isLoading: false,
    fetchError: null
  }
},
watch: {
  '$route': function () {
    var self = this
    self.isLoading = true
    self.fetchData().then(function () {
      self.isLoading = false
    })
  }
},
methods: {
  fetchData: function () {
    var self = this
    return axios.get('/api/posts')
      .then(function (response) {
        self.posts = response.data.posts
      })
      .catch(function (error) {
        self.fetchError = error
      })
  }
}

Upgrade Path

To find examples of the $loadingRouteData meta property, run the migration on your codebase.

Previous: Migrating from Vue 1.x
Next: Migrating from Vuex 0.6.x to 1.0