addRouteMiddleware

addRouteMiddleware() is a helper function to dynamically add middleware in your application.
Route middleware are navigation guards stored in the app/middleware/ directory of your Nuxt application (unless set otherwise).

Type

Signature
function addRouteMiddleware (name: string, middleware: RouteMiddleware, options?: AddRouteMiddlewareOptions): () => void
function addRouteMiddleware (middleware: RouteMiddleware): () => void

interface AddRouteMiddlewareOptions {
  global?: boolean
}

Parameters

name

  • Type: string | RouteMiddleware

Can be either a string or a function of type RouteMiddleware. Function takes the next route to as the first argument and the current route from as the second argument, both of which are Vue route objects.

Learn more about available properties of route objects.

middleware

  • Type: RouteMiddleware

The second argument is a function of type RouteMiddleware. Same as above, it provides to and from route objects. It becomes optional if the first argument in addRouteMiddleware() is already passed as a function.

options

  • Type: AddRouteMiddlewareOptions

An optional options argument lets you set the value of global to true to indicate whether the router middleware is global or not (set to false by default).

Return Value

addRouteMiddleware() returns a function that removes the middleware again. This is useful for middleware that only applies for part of the lifetime of your app:

app/plugins/onboarding.ts
export default defineNuxtPlugin(() => {
  const onboarded = useCookie<boolean>('onboarded')
  if (onboarded.value) {
    return
  }

  const unregister = addRouteMiddleware((to) => {
    if (to.path !== '/onboarding') {
      return navigateTo('/onboarding')
    }
  })

  watch(onboarded, (value) => {
    if (value) {
      unregister()
    }
  })
})

When registering middleware from a component, call the returned function when the component is unmounted, for example with onScopeDispose(unregister). To guard leaving the current page, use onBeforeRouteLeave instead.

Removing a named middleware that overrides one in the app/middleware/ directory restores the original. If the name has since been registered again with a different function, the returned function does nothing.

Example

Named Route Middleware

Named route middleware is defined by providing a string as the first argument and a function as the second:

app/plugins/my-plugin.ts
export default defineNuxtPlugin(() => {
  addRouteMiddleware('named-middleware', () => {
    console.log('named middleware added in Nuxt plugin')
  })
})

When defined in a plugin, it overrides any existing middleware of the same name located in the app/middleware/ directory.

Global Route Middleware

Global route middleware can be defined in two ways:

  • Pass a function directly as the first argument without a name. It will automatically be treated as global middleware and applied on every route change.

    app/plugins/my-plugin.ts
    export default defineNuxtPlugin(() => {
      addRouteMiddleware((to, from) => {
        console.log('anonymous global middleware that runs on every route change')
      })
    })
  • Set an optional, third argument { global: true } to indicate whether the route middleware is global.

    app/plugins/my-plugin.ts
    export default defineNuxtPlugin(() => {
      addRouteMiddleware('global-middleware', (to, from) => {
        console.log('global middleware that runs on every route change')
      },
      { global: true },
      )
    })