Pages

Nuxt Kit provides a set of utilities to help you create and use pages. You can use these utilities to manipulate the pages configuration or to define route rules.

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.

Watch Vue School video about extendPages.

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.

PropertyTypeRequiredDescription
namestringfalseThe name of the route. Useful for programmatic navigation and identifying routes.
pathstringfalseThe route URL path. If not set, Nuxt will infer it from the file location.
filestringfalsePath to the Vue file that should be used as the component for the route.
metaRecord<string, any>falseCustom metadata for the route. Can be used in layouts, middlewares, or navigation guards.
aliasstring[] | stringfalseOne or more alias paths for the route. Useful for supporting multiple URLs.
redirectRouteLocationRawfalseRedirect rule for the route. Supports named routes, objects, or string paths.
childrenNuxtPage[]falseNested 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.

You can read more about Nitro route rules in the Nitro documentation.
Watch Vue School video about adding route rules and route middelwares.

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.

About route rules configurations, you can get more detail in Hybrid Rendering > Route Rules.

options: A object to pass to the route configuration. If override is set to true, it will override the existing route configuration.

NameTypeDefaultDescription
overridebooleanfalseOverride 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.

Read more about route middlewares in the Route middleware documentation.
Watch Vue School video about adding route rules and route middelwares.

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 })
  },
})

Type

function addRouteMiddleware(input: NuxtMiddleware | NuxtMiddleware[], options?: AddRouteMiddlewareOptions): void

Parameters

input: A middleware object or an array of middleware objects with the following properties:

PropertyTypeRequiredDescription
namestringtrueThe name of the middleware.
pathstringtrueThe file path to the middleware.
globalbooleanfalseIf set to true, applies middleware to all routes.

options: An object with the following properties:

PropertyTypeDefaultDescription
overridebooleanfalseIf true, replaces middleware with the same name.
prependbooleanfalseIf true, prepends middleware before existing middlewares.