diff --git a/docs/content/2.guide/3.directory-structure/8.middleware.md b/docs/content/2.guide/3.directory-structure/8.middleware.md index 8f90cf9a21d..d25d3249833 100644 --- a/docs/content/2.guide/3.directory-structure/8.middleware.md +++ b/docs/content/2.guide/3.directory-structure/8.middleware.md @@ -41,10 +41,20 @@ Nuxt provides two globally available helpers that can be returned directly from Unlike navigation guards in [the vue-router docs](https://router.vuejs.org/guide/advanced/navigation-guards.html#global-before-guards), a third `next()` argument is not passed, and redirects or route cancellation is handled by returning a value from the middleware. Possible return values are: * nothing - does not block navigation and will move to the next middleware function, if any, or complete the route navigation -* `navigateTo('/')` or `navigateTo({ path: '/' })` - redirects to the given path and will set the redirect code to [`302` Found](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302) if the redirect happens on the server side -* `navigateTo('/', { redirectCode: 301 })` - redirects to the given path and will set the redirect code to [`301` Moved Permanently](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/301) if the redirect happens on the server side -* `abortNavigation()` - stops the current navigation -* `abortNavigation(error)` - rejects the current navigation with an error +* `return navigateTo('/')` or `return navigateTo({ path: '/' })` - redirects to the given path and will set the redirect code to [`302` Found](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302) if the redirect happens on the server side +* `return navigateTo('/', { redirectCode: 301 })` - redirects to the given path and will set the redirect code to [`301` Moved Permanently](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/301) if the redirect happens on the server side + +::ReadMore{link="/api/utils/navigate-to"} +:: + +* `return abortNavigation()` - stops the current navigation +* `return abortNavigation(error)` - rejects the current navigation with an error + +::ReadMore{link="/api/utils/abort-navigation"} +:: + +::ReadMore{link="/guide/features/routing"} +:: ::alert{type=warning} We recommend using the helper functions above for performing redirects or stopping navigation. Other possible return values described in [the vue-router docs](https://router.vuejs.org/guide/advanced/navigation-guards.html#global-before-guards) may work but there may be breaking changes in future. diff --git a/docs/content/3.api/3.utils/navigate-to.md b/docs/content/3.api/3.utils/navigate-to.md index c65a8b8427c..636e3e5990b 100644 --- a/docs/content/3.api/3.utils/navigate-to.md +++ b/docs/content/3.api/3.utils/navigate-to.md @@ -1,7 +1,76 @@ # `navigateTo` -::ReadMore{link="/guide/features/routing"} +`navigateTo` is a router helper function that allows creating programmatic navigation for users to navigate within Nuxt application. + +`navigateTo` is available on both server side and client side. It can be used within plugins, middleware or can be called directly to perform page navigation. + +## Usage + +```ts +navigateTo (route: string | Route, { redirectCode = 302, replace = false }) +``` + +`route` can be a plain string or a route object to redirect to. + +::alert{type="warning"} +Make sure to use always `await` or `return` on result of `navigateTo()` when calling it. :: -::NeedContribution +## Examples + +### Within a Vue component + +```vue + +``` + +### Within route middleware + +```js +export default defineNuxtRouteMiddleware((to, from) => { + // set the redirect code to 301 Moved Permanently + return navigateTo('/search', { redirectCode: 301 }) +}) +``` + +```js + +``` + +::ReadMore{link="/guide/directory-structure/middleware"} :: + +### Options + +#### `redirectCode` + +- Type: Number + +`navigateTo` redirects to the given path and sets the redirect code to [`302` Found](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302) by default when the redirect takes place on the server side. + +This default behavior can be modified by providing different `redirectCode` as an optional parameter. Commonly [`301` Moved Permanently](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/301) can be used for permant redirections. + +#### `replace` + +- Type: Boolean + +By default, `navigateTo` pushes the given route into Vue router instance on client-side. + +This behavior can be changed by setting `replace` to `true`, to indicate that given route should be replaced.