feat(nuxt): custom history and routes for app/router.options.ts (#7129)

Co-authored-by: Pooya Parsa <pooya@pi0.io>

docs/content/2.guide/3.directory-structure/10.pages.md

@@ -327,19 +327,56 @@ Learn more about [`<NuxtLink>`](/api/components/nuxt-link) usage.
 
 ## Router Options
 
-It is possible to set default [vue-router options](https://router.vuejs.org/api/interfaces/routeroptions.html).
-
-**Note:** `history` and `routes` options will be always overridden by Nuxt.
+It is possible to cutomize [vue-router options](https://router.vuejs.org/api/interfaces/routeroptions.html).
 
 ### Using `app/router.options`
 
 This is the recommended way to specify router options.
 
 ```js [app/router.options.ts]
-import type { RouterConfig } from '@nuxt/schema'
+import type { RouterOptions } from '@nuxt/schema'
 
 // https://router.vuejs.org/api/interfaces/routeroptions.html
-export default <RouterConfig>{
+export default <RouterOptions> {
+}
+```
+
+#### Custom Routes
+
+:StabilityEdge{title="custom routes"}
+
+You can optionally override routes using a function that accepts scanned routes and returns customized routes.
+If returning `null` or `undefined`, Nuxt will fallback to the default routes. (useful to modify input array)
+
+```js [app/router.options.ts]
+import type { RouterOptions } from '@nuxt/schema'
+
+// https://router.vuejs.org/api/interfaces/routeroptions.html
+export default <RouterOptions> {
+  routes: (_routes) => [
+    {
+      name: 'home',
+      route: '/',
+      component: () => import('~/pages/home.vue')
+    }
+  ],
+}
+```
+
+#### Custom History (advanced)
+
+:StabilityEdge{title="custom history"}
+
+You can optionally override history mode using a function that accepts base url and returns history mode.
+If returning `null` or `undefined`, Nuxt will fallback to the default history.
+
+```js [app/router.options.ts]
+import type { RouterOptions } from '@nuxt/schema'
+import { createWebHashHistory } from 'vue-router'
+
+// https://router.vuejs.org/api/interfaces/routeroptions.html
+export default <RouterOptions> {
+  history: (base) => process.client ? createWebHashHistory(base) : null /* use default */
 }
 ```
 

packages/nuxt/src/pages/runtime/router.ts

@@ -11,7 +11,7 @@ import { withoutBase, isEqual } from 'ufo'
 import NuxtPage from './page'
 import { callWithNuxt, defineNuxtPlugin, useRuntimeConfig, showError, clearError, navigateTo, useError, useState } from '#app'
 // @ts-ignore
-import routes from '#build/routes'
+import _routes from '#build/routes'
 // @ts-ignore
 import routerOptions from '#build/router.options'
 // @ts-ignore
@@ -55,14 +55,16 @@ export default defineNuxtPlugin(async (nuxtApp) => {
   nuxtApp.vueApp.component('NuxtChild', NuxtPage)
 
   const baseURL = useRuntimeConfig().app.baseURL
-  const routerHistory = process.client
-    ? createWebHistory(baseURL)
-    : createMemoryHistory(baseURL)
+
+  const history = routerOptions.history?.(baseURL) ??
+    (process.client ? createWebHistory(baseURL) : createMemoryHistory(baseURL))
+
+  const routes = routerOptions.routes?.(_routes) ?? _routes
 
   const initialURL = process.server ? nuxtApp.ssrContext!.url : createCurrentLocation(baseURL, window.location)
   const router = createRouter({
     ...routerOptions,
-    history: routerHistory,
+    history,
     routes
   })
   nuxtApp.vueApp.use(router)

packages/schema/src/types/router.ts

@@ -1,10 +1,12 @@
-import type { RouterOptions as _RouterOptions  } from 'vue-router'
+import type { RouterOptions as _RouterOptions, RouterHistory } from 'vue-router'
 
 
-export type RouterConfig = Partial<Omit<_RouterOptions, 'history' | 'routes'>>
+export type RouterOptions = Partial<Omit<_RouterOptions, 'history' | 'routes'>> & {
+  history?: (baseURL?: string) => RouterHistory
+  routes?: (_routes: _RouterOptions['routes']) => _RouterOptions['routes']
+}
 
-/** @deprecated Use RouterConfig instead */
-export type RouterOptions = RouterConfig
+export type RouterConfig = RouterOptions
 
 /**
  * Only JSON serializable router options are configurable from nuxt config