From 0c49e8cfb7be7f210f73381472974c92702fffb3 Mon Sep 17 00:00:00 2001
From: Krutie Patel <krutie.patel@gmail.com>
Date: Fri, 26 Aug 2022 20:56:22 +1000
Subject: [PATCH] docs(api): add `defineNuxtRouteMiddleware` util (#6933)

---
 .../3.utils/define-nuxt-route-middleware.md   | 61 ++++++++++++++++++-
 1 file changed, 58 insertions(+), 3 deletions(-)

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 a860c3ef4e..58cbcc6866 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`
 
+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<NavigationGuard>
+}
+```
+
+## 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)**.
+
+## 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"}
 ::
-
-::NeedContribution
-::