diff --git a/docs/3.api/3.utils/navigate-to.md b/docs/3.api/3.utils/navigate-to.md index 270bc80a00..2edc959529 100644 --- a/docs/3.api/3.utils/navigate-to.md +++ b/docs/3.api/3.utils/navigate-to.md @@ -8,16 +8,16 @@ links: size: xs --- -::note -`navigateTo` is available on both client and server side (but not within Nitro routes). -:: - ## Usage `navigateTo` is available on both server side and client side. It can be used within the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context), or directly, to perform page navigation. -::tip -To send a redirect from a server endpoint, use [`sendRedirect`](https://h3.unjs.io/utils/response#sendredirectevent-location-code) instead. +::warning +Make sure to always use `await` or `return` on result of `navigateTo` when calling it. +:: + +::note +`navigateTo` cannot be used within Nitro routes. To perform a server-side redirect in Nitro routes, use [`sendRedirect`](https://h3.unjs.io/utils/response#sendredirectevent-location-code) instead. :: ### Within a Vue Component @@ -52,9 +52,25 @@ export default defineNuxtRouteMiddleware((to, from) => { }) ``` +When using `navigateTo` within route middleware, you must **return its result** to ensure the middleware execution flow works correctly. + +For example, the following implementation **will not work as expected**: + +```ts +export default defineNuxtRouteMiddleware((to, from) => { + if (to.path !== '/search') { + // ❌ This will not work as expected + navigateTo('/search', { redirectCode: 301 }) + return + } +}) +``` + +In this case, `navigateTo` will be executed but not returned, which may lead to unexpected behavior. + :read-more{to="/docs/guide/directory-structure/middleware"} -### External URL +### Navigating to an External URL The `external` parameter in `navigateTo` influences how navigating to URLs is handled: @@ -81,7 +97,7 @@ await navigateTo('https://nuxt.com', { ``` -### Using open() +### Opening a Page in a New Tab ```vue