Pages
extendPages
In Nuxt, routes are automatically generated based on the structure of the files in the pages
directory. However, there may be scenarios where you'd want to customize these routes. For instance, you might need to add a route for a dynamic page not generated by Nuxt, remove an existing route, or modify the configuration of a route. For such customizations, Nuxt offers the extendPages
feature, which allows you to extend and alter the pages configuration.
Usage
import { createResolver, defineNuxtModule, extendPages } from '@nuxt/kit'
export default defineNuxtModule({
setup (options) {
const { resolve } = createResolver(import.meta.url)
extendPages((pages) => {
pages.unshift({
name: 'prismic-preview',
path: '/preview',
file: resolve('runtime/preview.vue'),
})
})
},
})
Type
function extendPages(callback: (pages: NuxtPage[]) => void): void
Parameters
callback: A function that will be called with the pages configuration. You can alter this array by adding, deleting, or modifying its elements. Note: You should modify the provided pages array directly, as changes made to a copied array will not be reflected in the configuration.
Property | Type | Required | Description |
---|---|---|---|
name | string | false | The name of the route. Useful for programmatic navigation and identifying routes. |
path | string | false | The route URL path. If not set, Nuxt will infer it from the file location. |
file | string | false | Path to the Vue file that should be used as the component for the route. |
meta | Record<string, any> | false | Custom metadata for the route. Can be used in layouts, middlewares, or navigation guards. |
alias | string[] | string | false | One or more alias paths for the route. Useful for supporting multiple URLs. |
redirect | RouteLocationRaw | false | Redirect rule for the route. Supports named routes, objects, or string paths. |
children | NuxtPage[] | false | Nested child routes under this route for layout or view nesting. |
extendRouteRules
Nuxt is powered by the Nitro server engine. With Nitro, you can incorporate high-level logic directly into your configuration, which is useful for actions like redirects, proxying, caching, and appending headers to routes. This configuration works by associating route patterns with specific route settings.
Usage
import { createResolver, defineNuxtModule, extendPages, extendRouteRules } from '@nuxt/kit'
export default defineNuxtModule({
setup (options) {
const { resolve } = createResolver(import.meta.url)
extendPages((pages) => {
pages.unshift({
name: 'preview-new',
path: '/preview-new',
file: resolve('runtime/preview.vue'),
})
})
extendRouteRules('/preview', {
redirect: {
to: '/preview-new',
statusCode: 302,
},
})
extendRouteRules('/preview-new', {
cache: {
maxAge: 60 * 60 * 24 * 7,
},
})
},
})
Type
function extendRouteRules(route: string, rule: NitroRouteConfig, options?: ExtendRouteRulesOptions): void
Parameters
route: A route pattern to match against.
rule: A route rule configuration to apply to the matched route.
options: A object to pass to the route configuration. If override
is set to true
, it will override the existing route configuration.
Name | Type | Default | Description |
---|---|---|---|
override | boolean | false | Override route rule config, default is false |
addRouteMiddleware
Registers route middlewares to be available for all routes or for specific routes.
Route middlewares can be also defined in plugins via addRouteMiddleware
composable.
Usage
import { addRouteMiddleware, createResolver, defineNuxtModule } from '@nuxt/kit'
export default defineNuxtModule({
setup () {
const { resolve } = createResolver(import.meta.url)
addRouteMiddleware({
name: 'auth',
path: resolve('runtime/auth.ts'),
global: true,
}, { prepend: true })
},
})
export default defineNuxtRouteMiddleware((to, from) => {
// isAuthenticated() is an example method verifying if a user is authenticated
if (to.path !== '/login' && isAuthenticated() === false) {
return navigateTo('/login')
}
})
Type
function addRouteMiddleware(input: NuxtMiddleware | NuxtMiddleware[], options?: AddRouteMiddlewareOptions): void
Parameters
input: A middleware object or an array of middleware objects with the following properties:
Property | Type | Required | Description |
---|---|---|---|
name | string | true | The name of the middleware. |
path | string | true | The file path to the middleware. |
global | boolean | false | If set to true , applies middleware to all routes. |
options: An object with the following properties:
Property | Type | Default | Description |
---|---|---|---|
override | boolean | false | If true , replaces middleware with the same name. |
prepend | boolean | false | If true , prepends middleware before existing middlewares. |