diff --git a/docs/content/3.api/3.utils/define-nuxt-route-middleware.md b/docs/content/3.api/3.utils/define-nuxt-route-middleware.md index a860c3ef4e0..58cbcc68661 100644 --- a/docs/content/3.api/3.utils/define-nuxt-route-middleware.md +++ b/docs/content/3.api/3.utils/define-nuxt-route-middleware.md @@ -1,7 +1,62 @@ # `defineNuxtRouteMiddleware` -::ReadMore{link="/guide/features/routing"} -:: +You can create named route middleware using `defineNuxtRouteMiddleware` helper function. + +Route middleware are stored in the `middleware/` directory of your Nuxt application (unless [set otherwise](/api/configuration/nuxt.config#middleware)). + +## Type + +```ts +defineNuxtRouteMiddleware(middleware: RouteMiddleware) => RouteMiddleware + +interface RouteMiddleware { + (to: RouteLocationNormalized, from: RouteLocationNormalized): ReturnType +} +``` + +## Parameters + +### `middleware` + +- **Type**: `RouteMiddleware` + +A function that takes two Vue Router's route location objects as parameters: the next route `to` as the first, and the current route `from` as the second. + +Learn more about available properties of `RouteLocationNormalized` in theĀ **[Vue Router docs](https://router.vuejs.org/api/interfaces/RouteLocationNormalized.html)**. -::NeedContribution +## Examples + +### Showing Error Page + +You can use route middleware to throw errors and show helpful error messages: + +```ts [middleware/error.ts] +export default defineNuxtRouteMiddleware((to) => { + if (to.params.id === '1') { + throw createError({ statusCode: 404, statusMessage: 'Page Not Found' }) + } +}) +``` + +The above route middleware will redirect a user to the custom error page defined in the `~/error.vue` file, and expose the error message and code passed from the middleware. + +### Redirection + +You can use `useState` in combination with `navigateTo` helper function inside the route middleware to redirect users to different routes based on their authentication status: + +```ts [middleware/auth.ts] +export default defineNuxtRouteMiddleware((to, from) => { + const auth = useState('auth') + + if (!auth.value.isAuthenticated) { + return navigateTo('/login') + } + + return navigateTo('/dashboard') +}) +``` + +Both [navigateTo](/api/utils/navigate-to) and [abortNavigation](/api/utils/abort-navigation) are globally available helper functions that you can use inside `defineNuxtRouteMiddleware`. + +::ReadMore{link="/guide/features/routing"} ::