diff --git a/docs/content/2.guide/3.directory-structure/10.pages.md b/docs/content/2.guide/3.directory-structure/10.pages.md index e5845521744..6a1568e1cc9 100644 --- a/docs/content/2.guide/3.directory-structure/10.pages.md +++ b/docs/content/2.guide/3.directory-structure/10.pages.md @@ -327,19 +327,56 @@ Learn more about [``](/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 { +} +``` + +#### 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 { + 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 { +export default { + history: (base) => process.client ? createWebHashHistory(base) : null /* use default */ } ``` diff --git a/packages/nuxt/src/pages/runtime/router.ts b/packages/nuxt/src/pages/runtime/router.ts index 32163890039..15e8a69d888 100644 --- a/packages/nuxt/src/pages/runtime/router.ts +++ b/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) diff --git a/packages/schema/src/types/router.ts b/packages/schema/src/types/router.ts index 03e0fabdc8b..52980134f35 100644 --- a/packages/schema/src/types/router.ts +++ b/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> +export type RouterOptions = Partial> & { + 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