Migrating to Vue Router 5

✨Vibe code Vue apps with confidence

RuleKit

TIP

Vue Router 5 is a transition release that merges unplugin-vue-router (file-based routing) into the core package. If you're using Vue Router 4 without unplugin-vue-router, there are no breaking changes - you can upgrade without any code modifications.

Vue Router 6 will be ESM-only and remove deprecated APIs. v5 gives you time to prepare for that transition.

For Vue Router 4 Users (without file-based routing)

No breaking changes. Update your dependency and you're done:

pnpm update vue-router@5

From unplugin-vue-router

If you were using unplugin-vue-router for file-based routing, migration is mostly import path changes.

Migration Checklist (TLDR)

• Remove unplugin-vue-routerdependency
• Update vue-routerto v5
• Change plugin import: unplugin-vue-router/vite → vue-router/vite
• Change data loader imports: unplugin-vue-router/data-loaders/* → vue-router/experimental
• Change utility imports: unplugin-vue-router → vue-router/unplugin
• Change Volar plugins: unplugin-vue-router/volar/* → vue-router/volar/*
• Remove unplugin-vue-router/clientfrom tsconfig / env.d.ts

1. Update Dependencies

pnpm remove unplugin-vue-router
pnpm update vue-router@5

2. Update Imports

Vite plugin:

import VueRouter from 'unplugin-vue-router/vite'
import VueRouter from 'vue-router/vite'

Other build tools (Webpack, Rollup, esbuild) import from vue-router/unplugin:

import VueRouter from 'vue-router/unplugin'

VueRouter.webpack({
  /* ... */
})
VueRouter.rollup({
  /* ... */
})
// etc.

Data loaders:

import { defineBasicLoader } from 'unplugin-vue-router/data-loaders/basic'
import { defineColadaLoader } from 'unplugin-vue-router/data-loaders/pinia-colada'
import { DataLoaderPlugin } from 'unplugin-vue-router/data-loaders'
import { defineBasicLoader, DataLoaderPlugin } from 'vue-router/experimental'
import { defineColadaLoader } from 'vue-router/experimental/pinia-colada'

Unplugin utilities (for custom integrations):

import {
  VueRouterAutoImports,
  EditableTreeNode,
  createTreeNodeValue,
  createRoutesContext,
  getFileBasedRouteName,
  getPascalCaseRouteName,
} from 'unplugin-vue-router'
} from 'vue-router/unplugin'

Types:

import type { Options, EditableTreeNode } from 'unplugin-vue-router'
import type { Options, EditableTreeNode } from 'vue-router/unplugin'

Volar plugins:

// tsconfig.json
{
  "compilerOptions": {
    "rootDir": ".",
  },
  "vueCompilerOptions": {
    "plugins": [
      "unplugin-vue-router/volar/sfc-typed-router", 
      "unplugin-vue-router/volar/sfc-route-blocks", 
    ],
  },
}

// tsconfig.json
{
  "compilerOptions": {
    "rootDir": ".",
  },
  "vueCompilerOptions": {
    "plugins": [
      "vue-router/volar/sfc-typed-router", 
      "vue-router/volar/sfc-route-blocks", 
    ],
  },
}

3. Update tsconfig.json

It's recommended to move the generated types file inside src/ and rename it to route-map.d.ts, as it's automatically included by most setups:

// vite.config.ts
export default defineConfig({
  plugins: [
    VueRouter({
      dts: 'src/route-map.d.ts', 
    }),
    Vue(),
  ],
})

Remove the old client types reference. These were either added to an env.d.ts:

/// <reference types="unplugin-vue-router/client" />

or to your tsconfig.json:

{
  "include": [
    "./typed-router.d.ts", 
    "unplugin-vue-router/client", 
    "./route-map.d.ts", 
  ],
}

Troubleshooting

Types not recognized: Restart your TypeScript server and check that your generated types file (e.g., route-map.d.ts) is included in your tsconfig.

Routes not generating: Verify your routesFolder path and check file extensions.

Route name errors: Use the generated names or add definePage({ name: 'custom-name' }) to your components.

New Exports Reference

Export	Purpose
vue-router	Main API (unchanged)
vue-router/vite	Vite plugin
vue-router/auto-routes	Generated routes
vue-router/unplugin	Webpack/Rollup/esbuild + utilities
vue-router/experimental	Data loaders
vue-router/experimental/pinia-colada	Pinia Colada loader