feat: allow overriding the global Router type

Author: posva

packages/router/src/config.ts

@@ -1,6 +1,7 @@
 /**
  * Allows customizing existing types of the router that are used globally like `$router`, `<RouterLink>`, etc. **ONLY FOR INTERNAL USAGE**.
  *
+ * - `Router` - swaps the public {@link Router} type (e.g. to `EXPERIMENTAL_Router`)
  * - `$router` - the router instance
  * - `$route` - the current route location
  * - `beforeRouteEnter` - Page component option

packages/router/src/index.ts

@@ -144,7 +144,8 @@ export type {
 } from './typed-routes'
 
 export { createRouter } from './router'
-export type { Router, RouterOptions } from './router'
+export type { RouterOptions } from './router'
+export type { Router as _RouterClassic } from './router'
 export type { RouterScrollBehavior } from './scrollBehavior'
 
 export { NavigationFailureType, isNavigationFailure } from './errors'
@@ -174,7 +175,7 @@ export * from './useApi'
 
 // Global extensions for Vue
 import type { TypesConfig } from './config'
-import type { Router } from './router'
+import type { Router as RouterClassic } from './router'
 import type { RouterLink } from './RouterLink'
 import type { RouterView } from './RouterView'
 import type {
@@ -183,6 +184,25 @@ import type {
   RouteLocationNormalizedLoaded,
 } from './typed-routes'
 
+/**
+ * Router instance.
+ *
+ * By default this resolves to the classic {@link RouterClassic}. Augment
+ * {@link TypesConfig} with a `Router` slot to swap the public type — for
+ * example to the experimental router:
+ *
+ * ```ts
+ * import type { EXPERIMENTAL_Router } from 'vue-router/experimental'
+ * declare module 'vue-router' {
+ *   interface TypesConfig {
+ *     Router: EXPERIMENTAL_Router
+ *   }
+ * }
+ * ```
+ */
+export type Router =
+  TypesConfig extends Record<'Router', infer T> ? T : RouterClassic
+
 declare module 'vue' {
   export interface ComponentCustomOptions {
     /**

packages/router/src/router.ts

@@ -1013,6 +1013,8 @@ export function createRouter(options: RouterOptions): Router {
       app.component('RouterLink', RouterLink)
       app.component('RouterView', RouterView)
 
+      // augmented to the experimental shape it diverges from `createRouter`'s
+      // return type. FIXME.
       app.config.globalProperties.$router = router as Router
       Object.defineProperty(app.config.globalProperties, '$route', {
         enumerable: true,

packages/router/tsconfig.json

@@ -17,6 +17,7 @@
     "outDir": "dist",
     "sourceMap": false,
     "noEmit": true,
+    "composite": true,
     "target": "esnext",
     "module": "esnext",
     "moduleResolution": "Bundler",