This merges unplugin-vue-router into vue-router with minimal breaking changes. The goal is to release a v5 that is the closest possible to vue-router 4 to ease migration, then release a v6 that has other breaking changes like ESM only, removed deprecated features, improvements for types, etc

Vue Router 5 Migration Guide

Vue Router 5 merges unplugin-vue-router into the core package.

Migrating from unplugin-vue-router

If you're already using unplugin-vue-router, migration is straightforward—mostly import changes.

1. Update Dependencies

pnpm remove unplugin-vue-router
# once published
pnpm update vue-router@5
# for the moment
pnpm add https://pkg.pr.new/vue-router@2603

2. Update Imports

Vite plugin:

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

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

Data loaders:

// Before
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'

// After
import { defineBasicLoader, DataLoaderPlugin } from 'vue-router/experimental'
import { defineColadaLoader } from 'vue-router/experimental/pinia-colada'

Unplugin utilities (for custom integrations):

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

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

Types:

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

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

Volar plugins:

// Before (tsconfig.json)
{
  "compilerOptions": {
    // needed for the volar plugin
    "rootDir": "."
  },
  "vueCompilerOptions": {
    "plugins": [
      "unplugin-vue-router/volar/sfc-typed-router",
      "unplugin-vue-router/volar/sfc-route-blocks"
    ]
  }
}

// After
{
  "compilerOptions": {
    // needed for the volar plugin
    "rootDir": "."
  },
  "vueCompilerOptions": {
    "plugins": [
      "vue-router/volar/sfc-typed-router",
      "vue-router/volar/sfc-route-blocks"
    ]
  }
}

3. Update tsconfig.json

Remove the old client types reference:

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

// After
{
  "include": ["./typed-router.d.ts"]
}

Migration Checklist (unplugin-vue-router)

• Remove unplugin-vue-router dependency
• Update vue-router to 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/client from tsconfig

Migrating from Vue Router 4 (without file-based routing)

1. Add Build Plugin

Vite:

// vite.config.ts
import VueRouter from 'vue-router/vite'

export default defineConfig({
  plugins: [
    VueRouter({
      // Recommended: auto-included by tsconfig
      dts: 'src/typed-router.d.ts',
    }),
    vue(),
  ],
})

Tip: Using dts: 'src/typed-router.d.ts' places the generated types inside src/, which is automatically included by most tsconfig.json setups. This will become the default in a future version.

Webpack:

// webpack.config.js
const VueRouter = require('vue-router/unplugin').default

module.exports = {
  plugins: [
    VueRouter.webpack({
      dts: 'src/typed-router.d.ts',
    }),
  ],
}

Rollup:

// rollup.config.js
import VueRouter from 'vue-router/unplugin'

export default {
  plugins: [
    VueRouter.rollup({
      dts: 'src/typed-router.d.ts',
    }),
  ],
}

esbuild:

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

esbuild.build({
  plugins: [
    VueRouter.esbuild({
      dts: 'src/typed-router.d.ts',
    }),
  ],
})

2. Update Routes Import

// Before
import Home from '@/views/Home.vue'
const routes = [{ path: '/', component: Home }]

// After
import { routes } from 'vue-router/auto-routes'

3. TypeScript Configuration

If using the recommended dts: 'src/typed-router.d.ts', no changes needed—it's auto-included.

Otherwise, add the generated types file to your config:

// tsconfig.json
{
  "include": ["./typed-router.d.ts"]
}

4. Move Page Components

Components must move to src/pages/ (configurable via routesFolder).

5. Update Route Names

Names are auto-generated from file paths:

Update router.push() calls:

// Before
router.push({ name: 'user', params: { id: '123' } })

// After
router.push({ name: '/users/[id]', params: { id: '123' } })

To keep custom names, use definePage(), but it's recommended to let Vue Router manage names automatically for consistency.

<script setup lang="ts">
definePage({ name: 'user' })
</script>

6. File Naming Conventions

Dynamic routes:

Index routes with custom names:

Instead of index.vue, you can use parentheses to give the file a meaningful name without affecting the route:

This helps keep your codebase organized with descriptive file names and also allows to group related pages together.

Migration Checklist (Vue Router 4)

• Install vue-router@5
• Add build plugin with dts: 'src/typed-router.d.ts'
• Move page components to src/pages/
• Change routes import to vue-router/auto-routes
• Update router.push({ name: ... }) calls
• Add definePage() where custom names needed

Hybrid Migration (Keep Manual Routes)

Mix file-based and manual routes:

import type { RouteRecordRaw } from 'vue-router'
import { routes as autoRoutes } from 'vue-router/auto-routes'

const manualRoutes: RouteRecordRaw[] = [
  { path: '/legacy', component: () => import('@/legacy/Page.vue') },
]

const router = createRouter({
  history: createWebHistory(),
  routes: [...autoRoutes, ...manualRoutes],
})

Troubleshooting

Types not recognized: Restart TS server, check typed-router.d.ts in tsconfig

Routes not generating: Verify routesFolder path, check file extensions

Route name errors: Use new generated names or add definePage({ name: 'old-name' })

New Exports Reference

New Features

Volar Plugins for Enhanced IDE Support

Vue Router 5 includes Volar plugins that provide automatic typing in your IDE. No more passing route names to useRoute()!

Setup in tsconfig.json:

{
  "compilerOptions": {
    // needed for the volar plugin
    "rootDir": ".",
  },
  "vueCompilerOptions": {
    "plugins": [
      "vue-router/volar/sfc-typed-router",
      "vue-router/volar/sfc-route-blocks",
    ],
  },
  "include": ["./typed-router.d.ts"],
}

What you get:

sfc-typed-router — Automatic useRoute() and $route typing based on the current file:

<!-- src/pages/users/[id].vue -->
<script setup lang="ts">
// Before: had to pass route name for typing
const route = useRoute('/users/[id]')

// After: automatically typed based on file location!
const route = useRoute()
route.params.id // ✅ typed as string
</script>

<template>
  <!-- $route is also automatically typed -->
  <p>User ID: {{ $route.params.id }}</p>
</template>

sfc-route-blocks — JSON/YAML validation and autocomplete for <route> blocks:

<route lang="json">
{
  "$schema": "https://router.vuejs.org/schemas/route.schema.json",
  "name": "user-profile",
  "meta": { "requiresAuth": true }
}
</route>

Route Customization

Using definePage() macro

<script setup lang="ts">
definePage({
  name: 'custom-name',
  path: '/custom-path',
  meta: { requiresAuth: true },
  alias: ['/alternate'],
})
</script>

Using <route> block

<route lang="json5">
{
  name: 'custom-name',
  meta: { requiresAuth: true },
}
</route>

Using plugin config

VueRouter({
  extendRoute(route) {
    if (route.path === '/admin') {
      route.addToMeta({ requiresAdmin: true })
    }
  },
})

Plugin Configuration

VueRouter({
  routesFolder: 'src/pages',
  extensions: ['.vue'],
  exclude: ['**/components/**'],
  importMode: 'async',
  dts: 'src/typed-router.d.ts', // Recommended
  routeBlockLang: 'json5',
})