docs: migration list

diff --git a/packages/docs/.vitepress/theme/components/MigrationChecklist.vue b/packages/docs/.vitepress/theme/components/MigrationChecklist.vue
new file mode 100644 (file)
index 0000000..dc71164
--- /dev/null
+++ b/packages/docs/.vitepress/theme/components/MigrationChecklist.vue
@@ -0,0 +1,71 @@
+<script setup lang="ts">
+const items = [
+  { text: 'Remove', code: 'unplugin-vue-router', after: 'dependency' },
+  { text: 'Update', code: 'vue-router', after: 'to v5' },
+  {
+    text: 'Change plugin import:',
+    code: 'unplugin-vue-router/vite',
+    arrow: 'vue-router/vite',
+  },
+  {
+    text: 'Change data loader imports:',
+    code: 'unplugin-vue-router/data-loaders/*',
+    arrow: 'vue-router/experimental',
+  },
+  {
+    text: 'Change utility imports:',
+    code: 'unplugin-vue-router',
+    arrow: 'vue-router/unplugin',
+  },
+  {
+    text: 'Change Volar plugins:',
+    code: 'unplugin-vue-router/volar/*',
+    arrow: 'vue-router/volar/*',
+  },
+  {
+    text: 'Remove',
+    code: 'unplugin-vue-router/client',
+    after: 'from tsconfig / env.d.ts',
+  },
+]
+</script>
+
+<template>
+  <ul class="migration-checklist">
+    <li v-for="(item, i) in items" :key="i">
+      <label>
+        <input type="checkbox" />
+        <span>
+          {{ item.text }} <code>{{ item.code }}</code>
+          <template v-if="item.arrow">
+            → <code>{{ item.arrow }}</code></template
+          >
+          <template v-if="item.after"> {{ item.after }}</template>
+        </span>
+      </label>
+    </li>
+  </ul>
+</template>
+
+<style scoped>
+.migration-checklist {
+  list-style: none;
+  padding-left: 0;
+}
+
+.migration-checklist li {
+  margin: 0.5rem 0;
+}
+
+.migration-checklist label {
+  display: flex;
+  align-items: flex-start;
+  gap: 0.5rem;
+  cursor: pointer;
+}
+
+.migration-checklist input[type='checkbox'] {
+  margin-top: 0.3rem;
+  cursor: pointer;
+}
+</style>

diff --git a/packages/docs/guide/migration/v4-to-v5.md b/packages/docs/guide/migration/v4-to-v5.md
new file mode 100644 (file)
index 0000000..1bdde0a
--- /dev/null
+++ b/packages/docs/guide/migration/v4-to-v5.md
@@ -0,0 +1,174 @@
+# Migrating to Vue Router 5
+
+<RuleKitLink />
+
+> [!TIP]
+> Vue Router 5 is a transition release that merges [unplugin-vue-router](https://uvr.esm.is) (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:
+
+```bash
+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)
+
+<script setup>
+import MigrationChecklist from '../../.vitepress/theme/components/MigrationChecklist.vue'
+</script>
+
+<MigrationChecklist />
+
+### 1. Update Dependencies
+
+```bash
+pnpm remove unplugin-vue-router
+pnpm update vue-router@5
+```
+
+### 2. Update Imports
+
+**Vite plugin:**
+
+```ts
+import VueRouter from 'unplugin-vue-router/vite' // [!code --]
+import VueRouter from 'vue-router/vite' // [!code ++]
+```
+
+Other build tools (Webpack, Rollup, esbuild) import from `vue-router/unplugin`:
+
+```ts
+import VueRouter from 'vue-router/unplugin'
+
+VueRouter.webpack({
+  /* ... */
+})
+VueRouter.rollup({
+  /* ... */
+})
+// etc.
+```
+
+**Data loaders:**
+
+```ts
+import { defineBasicLoader } from 'unplugin-vue-router/data-loaders/basic' // [!code --]
+import { defineColadaLoader } from 'unplugin-vue-router/data-loaders/pinia-colada' // [!code --]
+import { DataLoaderPlugin } from 'unplugin-vue-router/data-loaders' // [!code --]
+import { defineBasicLoader, DataLoaderPlugin } from 'vue-router/experimental' // [!code ++]
+import { defineColadaLoader } from 'vue-router/experimental/pinia-colada' // [!code ++]
+```
+
+**Unplugin utilities (for custom integrations):**
+
+```ts
+import {
+  VueRouterAutoImports,
+  EditableTreeNode,
+  createTreeNodeValue,
+  createRoutesContext,
+  getFileBasedRouteName,
+  getPascalCaseRouteName,
+} from 'unplugin-vue-router' // [!code --]
+} from 'vue-router/unplugin' // [!code ++]
+```
+
+**Types:**
+
+```ts
+import type { Options, EditableTreeNode } from 'unplugin-vue-router' // [!code --]
+import type { Options, EditableTreeNode } from 'vue-router/unplugin' // [!code ++]
+```
+
+**Volar plugins:**
+
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "rootDir": ".",
+  },
+  "vueCompilerOptions": {
+    "plugins": [
+      "unplugin-vue-router/volar/sfc-typed-router", // [!code --]
+      "unplugin-vue-router/volar/sfc-route-blocks", // [!code --]
+    ],
+  },
+}
+```
+
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "rootDir": ".",
+  },
+  "vueCompilerOptions": {
+    "plugins": [
+      "vue-router/volar/sfc-typed-router", // [!code ++]
+      "vue-router/volar/sfc-route-blocks", // [!code ++]
+    ],
+  },
+}
+```
+
+### 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:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  plugins: [
+    VueRouter({
+      dts: 'src/route-map.d.ts', // [!code ++]
+    }),
+    Vue(),
+  ],
+})
+```
+
+Remove the old client types reference. These were either added to an `env.d.ts`:
+
+```ts
+/// <reference types="unplugin-vue-router/client" /> // [!code --]
+```
+
+or to your `tsconfig.json`:
+
+```jsonc
+{
+  "include": [
+    "./typed-router.d.ts", // [!code --]
+    "unplugin-vue-router/client", // [!code --]
+    "./route-map.d.ts", // [!code ++]
+  ],
+}
+```
+
+## 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                |