Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dvlkit/nuxe/llms.txt

Use this file to discover all available pages before exploring further.

Route middleware lets you run code before a navigation completes — checking authentication, verifying permissions, or redirecting users to the right page. Nuxe automatically discovers every .ts or .js file inside app/middleware/ and wires them into the router, so you never need to register them manually.

​
Types of middleware

Nuxe recognises three flavours of middleware based purely on the file name:

Named

Applied only to specific pages that opt in via definePage({ meta: { middleware: 'admin' } }). The middleware name is derived from the file name.

Global

Files ending in .global.ts run automatically on every navigation — client-side and SSR alike.

Server-only global

Files ending in .server.global.ts run during SSR only. They are skipped entirely after the app hydrates on the client.

​
File naming conventions

File nameKindRegistered name
admin.tsNamedadmin
auth.global.tsGlobal (client + SSR)—
auth.server.global.tsGlobal, SSR only—
01-auth.global.tsGlobal, runs first (ordered)—
_helpers.tsIgnored — _-prefix skips scanning—
Prefix a file with a number and a - or _ separator (e.g. 01-auth.global.ts) to control the order in which multiple global middlewares execute. Files without a numeric prefix are sorted after all numbered ones.
Files whose names start with _ are skipped by the middleware scanner. Use this convention for shared helper modules that should not be registered as middleware themselves.

​
defineNuxeRouteMiddleware

Every middleware file must export a default function wrapped in defineNuxeRouteMiddleware. This is a thin identity wrapper that provides TypeScript types — it accepts any Vue Router NavigationGuard. 
function defineNuxeRouteMiddleware(middleware: NavigationGuard): NavigationGuard
The guard receives the same (to, from) arguments as a standard Vue Router navigation guard and can return undefined (continue), a route location (redirect), or false (cancel).

​
Named middleware example

app/middleware/admin.ts guards the admin section. It logs the navigation and, in a real app, would redirect non-admin users away: 
// app/middleware/admin.ts
export default defineNuxeRouteMiddleware((to, from) => {
  console.log('[admin]', from.path, '->', to.path)

  // Example: redirect if the user is not an admin
  // if (!useAuthStore().isAdmin) {
  //   return navigateTo('/')
  // }
})
Apply it to a page with definePage: 
<!-- app/pages/dashboard.vue -->
<script setup lang="ts">
definePage({
  meta: { middleware: 'admin' }
})
</script>
You can also apply multiple middlewares by passing an array: 
definePage({
  meta: { middleware: ['auth', 'admin'] }
})

​
Global middleware example

app/middleware/auth.global.ts runs before every navigation without needing to opt in per page: 
// app/middleware/auth.global.ts
export default defineNuxeRouteMiddleware((to, from) => {
  console.log('[auth.global]', from.path, '->', to.path)

  // Example: redirect unauthenticated users to /login
  // if (!useAuthStore().isLoggedIn && to.path !== '/login') {
  //   return navigateTo('/login')
  // }
})

​
Server-only global middleware example

app/middleware/auth.server.global.ts is identical in structure but only executes during the initial server-side render — ideal for reading cookies or session data that only exist on the server: 
// app/middleware/auth.server.global.ts
export default defineNuxeRouteMiddleware((to, from) => {
  console.log('[auth.server.global]', from.path, '->', to.path)
})
Call navigateTo inside a middleware guard to redirect the user. It handles both client-side navigation and SSR HTTP redirects automatically. 
export default defineNuxeRouteMiddleware((to) => {
  // Redirect to login if not authenticated
  if (!isAuthenticated()) {
    return navigateTo('/login')
  }
})
​
to
RouteLocationRaw | string | null | undefined
required
The destination route. Pass a string path, a route location object, or null/undefined to continue navigation unchanged.
​
options.replace
boolean
Replace the current history entry instead of pushing a new one. Defaults to false.
​
options.redirectCode
number
HTTP status code used during SSR redirects. Defaults to 302. Has no effect on client-side navigation.
​
options.external
boolean
Treat to as an external URL and navigate via window.location.href (client) or an HTTP redirect (SSR). Required when redirecting outside the Vue Router.

​
Examples

// Standard redirect
return navigateTo('/login')

// Replace history entry (no back button)
return navigateTo('/dashboard', { replace: true })

// Permanent redirect on SSR
return navigateTo('/new-path', { redirectCode: 301 })

// External URL
return navigateTo('https://example.com', { external: true })

​
abortNavigation(err?)

Call abortNavigation to cancel the current navigation without redirecting. Optionally pass an error payload to surface a status code and message. 
export default defineNuxeRouteMiddleware((to) => {
  if (!hasPermission(to)) {
    return abortNavigation({
      statusCode: 403,
      statusMessage: 'Forbidden',
    })
  }
})
​
err
Error | string | { statusCode?: number; statusMessage?: string }
Optional error payload. Pass an Error, a plain string (becomes statusMessage), or an object with statusCode and statusMessage.

Build docs developers (and LLMs) love

Get started for freeTalk to us