composables: routing

13 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Example defining route middleware

Route middleware is defined using `export default defineNuxtRouteMiddleware((to, from) => { ... })`. Example: middleware can check route parameters and return `abortNavigation()` to prevent navigation, or check the path and return `navigateTo('/')` to redirect to a different route.

Three kinds of route middleware

Nuxt provides three kinds of route middleware: Anonymous (or inline) route middleware defined directly within the page; Named route middleware placed in the `app/middleware/` directory and automatically loaded via asynchronous import when used on a page; Global route middleware placed in the `app/middleware/` with a `.global` suffix and run on every route change.

Route middleware naming convention

Middleware names are normalized to kebab-case. For example, `myMiddleware` becomes `my-middleware`.

defineNuxtRouteMiddleware signature and usage

Route middleware are defined using `defineNuxtRouteMiddleware((to, from) => {})`. The middleware receives the current route (to) and the next route (from) as arguments. Middleware can return nothing to continue to the next middleware, `navigateTo(path)` to redirect, `navigateTo(path, { redirectCode: 301 })` to redirect with a specific HTTP status code, `abortNavigation()` to stop the current navigation, or `abortNavigation(error)` to reject the navigation with an error.

Route middleware helpers

Nuxt provides two globally available helper functions for route middleware: `navigateTo()` redirects to a given route and sets the redirect code to 302 Found on server-side redirects unless otherwise specified; `abortNavigation()` aborts the navigation with an optional error message.

Middleware execution order

Middleware runs in the following order: Global Middleware first (executed alphabetically by filename by default), then Page defined middleware in the order declared using array syntax. Global middleware can be ordered by prefixing filenames with numbers (e.g., 01.setup.global.ts, 02.analytics.global.ts). Filenames are sorted as strings, not numeric values.

Middleware execution on server and client

If a site is server-rendered or generated, middleware for the initial page is executed both on the server when the page is rendered and again on the client. This can be avoided by checking `import.meta.server` or `import.meta.client` in the middleware. To skip middleware only on initial client load after hydration, check `import.meta.client && nuxtApp.isHydrating && nuxtApp.payload.serverRendered`.

Accessing route in middleware

Always use the `to` and `from` parameters in middleware to access the next and previous routes. Avoid using the `useRoute()` composable in middleware because there is no concept of a 'current route' in middleware—middleware can abort a navigation or redirect to a different route, making `useRoute()` inaccurate. If calling a composable that uses `useRoute()` internally, pass the route as an argument instead.

addRouteMiddleware function

The `addRouteMiddleware(name, handler, options)` helper function allows adding global or named route middleware manually, such as from within a plugin. The function takes a middleware name, handler function, and an options object. Pass `{ global: true }` in options to create global middleware. Named middleware added dynamically will override any existing middleware with the same name.

definePageMeta for middleware

Anonymous and named route middleware can be defined in `definePageMeta` using the `middleware` property. It accepts either a string for a single middleware or an array of middleware names and inline middleware functions.

Setting middleware at build time

Named route middleware can be added to pages using the `pages:extend` hook in `nuxt.config.ts`. The hook receives an array of pages and allows setting or overriding the `middleware` property on `page.meta` at build time. Middleware set this way will override any middleware defined in `definePageMeta`.

useRoute composable for accessing route parameters

The global useRoute function allows you to access the route object in Composition API, similar to this.$route in Options API. You can access route parameters and other route information through this composable.

navigateTo utility for programmatic navigation

The navigateTo() utility method allows programmatic navigation. You must always await on navigateTo or chain its result by returning from functions. Example: return navigateTo({ path: '/search', query: { name: name.value, type: type.value } })

Give your agent this brain