fix: require explicit routes import to avoid cyclic imports

Fix #132

BREAKING CHANGE: `createRouter()` now requires the explicit `router`
property to be set and imported:

```diff
import { createRouter, createWebHistory } from 'vue-router/auto'
+import { routes } from 'vue-router/auto-routes'

createRouter({
  history: createWebHistory(),
+  routes
})
```

This also means that runtime `extendRoutes()` option is not needed. It
has been deprecated and will be removed in the next major release.

Author: posva

README.md

@@ -149,9 +149,7 @@ If you don't have an `env.d.ts` file, you can create one and add the unplugin-vu
 {
   "compilerOptions": {
     // ...
-    "types": [
-      "unplugin-vue-router/client"
-    ]
+    "types": ["unplugin-vue-router/client"]
   }
 }
 ```
@@ -161,11 +159,12 @@ Finally, you should replace your imports from `vue-router` to `vue-router/auto`:
 ```diff
 -import { createRouter, createWebHistory } from 'vue-router'
 +import { createRouter, createWebHistory } from 'vue-router/auto'
++import { routes } from 'vue-router/auto-routes'
 
 createRouter({
   history: createWebHistory(),
-  // You don't need to pass the routes anymore,
-  // the plugin writes it for you 🤖
+  // pass the generated routes written by the plugin 🤖
++  routes,
 })
 ```
 

docs/guide/extending-routes.md

@@ -89,37 +89,38 @@ The `<route>` custom block is a way to extend existing routes. It can be used to
 
 Note you can specify the language to use with `<route lang="yaml">`. By default, the language is JSON5 (more flexible version of JSON) but yaml and JSON are also supported.
 
-## `extendRoutes()`
+## Extending routes at runtime
 
-As an escape-hatch, it's possible to extend the routes **at runtime** with the `extendRoutes` option in `createRouter()`. Since these changes are made at runtime, they are not reflected in the generated `typed-router.d.ts` file.
+As an escape-hatch, it's possible to extend the routes **at runtime** by simply changing the `routes` array before passing it to `createRouter()`. Since these changes are made at runtime, they are not reflected in the generated `typed-router.d.ts` file.
 
-```js{4-12}
+```js{4-9}
 import { createWebHistory, createRouter } from 'vue-router/auto'
+import { routes } from 'vue-router/auto-routes'
+
+for (const route of routes) {
+  if (route.name === '/admin') {
+    adminRoute.meta ??= {}
+    adminRoute.meta.requiresAuth = true
+  }
+}
 
 const router = createRouter({
-  extendRoutes: (routes) => {
-    const adminRoute = routes.find((r) => r.name === '/admin')
-    if (adminRoute) {
-      adminRoute.meta ??= {}
-      adminRoute.meta.requiresAuth = true
-    }
-    // the return is completely optional since we are modifying the routes in place
-    return routes
-  },
   history: createWebHistory(),
+  routes,
 })
 ```
 
-As this plugin evolves, this function should be used less and less and only become necessary in unique edge cases.
+As this plugin evolves, this should be used less and less and only become necessary in unique edge cases.
 
-One example of this is using [vite-plugin-vue-layouts](https://github.com/JohnCampionJr/vite-plugin-vue-layouts) which can only be used alongside `extendRoutes()`:
+One example of this is using [vite-plugin-vue-layouts](https://github.com/JohnCampionJr/vite-plugin-vue-layouts) which can only be used this way:
 
 ```ts
 import { createRouter } from 'vue-router/auto'
+import { routes } from 'vue-router/auto-routes'
 import { setupLayouts } from 'virtual:generated-layouts'
 
 const router = createRouter({
   // ...
-  extendRoutes: (routes) => setupLayouts(routes),
+  routes: setupLayouts(routes),
 })
 ```

docs/introduction.md

@@ -179,6 +179,7 @@ Given the following route configuration:
 ```ts [src/router.ts]
 import { createRouter, createWebHistory } from 'vue-router' // [!code --]
 import { createRouter, createWebHistory } from 'vue-router/auto' // [!code ++]
+import { routes } from 'vue-router/auto-routes' // [!code ++]
 
 export const router = createRouter({
   history: createWebHistory(),
@@ -196,6 +197,7 @@ export const router = createRouter({
       component: () => import('src/pages/About.vue'), // [!code --]
     }, // [!code --]
   ] // [!code --]
+  routes, // [!code ++]
 })
 ```
 
@@ -222,14 +224,15 @@ Check the [file-based routing](/guide/file-based-routing) guide for more informa
 
 ::: code-group
 
-```ts{2,5-8,11} [src/main.ts]
+```ts{2-3,6-9,12} [src/main.ts]
 import { createApp } from 'vue'
 import { createRouter, createWebHistory } from 'vue-router/auto'
+import { routes } from 'vue-router/auto-routes'
 import App from './App.vue'
 
 const router = createRouter({
   history: createWebHistory(),
-  // the routes property is handled by the plugin
+  routes,
 })
 
 createApp(App)
@@ -247,9 +250,9 @@ createApp(App)
 
 Check the [file-based routing](/guide/file-based-routing) guide for more information about the naming conventions.
 
-### Passing the routes manually
+### Manipulating the routes
 
-Alternatively, **you can also import the `routes` array** and create the router manually or pass it to some plugin. Here is an example with [Vitesse starter](https://github.com/antfu/vitesse/blob/main/src/main.ts):
+You can pass the `routes` to any plugin that needs to add changes to them but note that **these changes will not be reflected in types**. Use [build-time routes instead](./guide//extending-routes.md) if you want to have types support. Here is an example with [Vitesse starter](https://github.com/antfu/vitesse/blob/main/src/main.ts):
 
 ```ts
 import { ViteSSG } from 'vite-ssg'

docs/rfcs/data-loaders/index.md

@@ -566,6 +566,7 @@ import { DataLoaderPlugin, createRouter, createWebHistory } from 'vue-router/aut
 const app = createApp({})
 const router = createRouter({
   history: createWebHistory(),
+  routes: [],
 })
 // ---cut---
 // @moduleResolution: bundler

playground/src/main.ts

@@ -5,16 +5,14 @@ import {
   createWebHistory,
   DataLoaderPlugin,
 } from 'vue-router/auto'
+import { routes } from 'vue-router/auto-routes'
 import { MutationCache, QueryCache, VueQueryPlugin } from '@tanstack/vue-query'
 import { createPinia } from 'pinia'
 import { QueryPlugin } from '@pinia/colada'
 
 const router = createRouter({
   history: createWebHistory(),
-  extendRoutes: (routes) => {
-    // routes.find((r) => r.name === '/')!.meta = {}
-    return routes
-  },
+  routes,
 })
 
 const app = createApp(App)

src/codegen/vueRouterModule.ts

@@ -9,7 +9,6 @@ export function generateVueRouterProxy(
   { addPiniaColada }: { addPiniaColada: boolean }
 ) {
   return `
-import { routes } from '${routesModule}'
 import { createRouter as _createRouter } from 'vue-router'
 
 export * from 'vue-router'
@@ -24,14 +23,19 @@ export * from 'unplugin-vue-router/data-loaders/basic'
 ${addPiniaColada ? "export * from 'unplugin-vue-router/data-loaders/pinia-colada'" : ''}
 
 export function createRouter(options) {
-  const { extendRoutes } = options
+  const { extendRoutes, routes } = options
   // use Object.assign for better browser support
+  if (extendRoutes) {
+    console.warn('"extendRoutes()" is deprecated, please modify the routes directly. See')
+  }
   const router = _createRouter(Object.assign(
     options,
-    { routes: typeof extendRoutes === 'function' ? extendRoutes(routes) : routes },
+    { routes: typeof extendRoutes === 'function' ? (extendRoutes(routes) || routes) : routes },
   ))
 
   return router
 }
 `.trimStart()
 }
+
+// FIXME: remove `extendRoutes()` in the next major version

src/core/vite/index.ts

@@ -1,4 +1,4 @@
-import { ViteDevServer } from 'vite'
+import { type ViteDevServer } from 'vite'
 import { ServerContext } from '../../options'
 import { asVirtualId } from '../moduleConstants'
 

src/data-loaders/navigation-guard.ts

@@ -325,14 +325,8 @@ export class NavigationResult {
  *
  * @example
  * ```ts
- * import { createApp } from 'vue'
- * import {
- *   createRouter,
- *   DataLoaderPlugin,
- *   createWebHistory,
- * } from 'vue-router/auto'
- *
  * const router = createRouter({
+ *   routes,
  *   history: createWebHistory(),
  * })
  *

src/type-extensions/router.ts

@@ -152,12 +152,14 @@ export type _Router =
 
 /**
  * unplugin-vue-router version of `RouterOptions`.
+ * @deprecated use `RouterOptions` instead. This type is no longer needed.
  * @see {@link RouterOptions}
  */
-export interface _RouterOptions extends Omit<RouterOptions, 'routes'> {
+export interface _RouterOptions extends RouterOptions {
   /**
    * Modify the routes before they are passed to the router. You can modify the existing array or return a
    * new one.
+   * @deprecated `routes` is now required, so you can just modify a copy of the array directly.
    *
    * @param routes - The routes generated by this plugin and exposed by `vue-router/auto-routes`
    */

src/types.ts

@@ -49,6 +49,7 @@ export type {
   // TODO: deprecate and remove
   _RouterTyped,
   _Router as Router,
+  // FIXME: remove in the next major version
   _RouterOptions,
 } from './type-extensions/router'
 export type {