@nuxt/docs-nightly 5.0.0-29787185.8dc3f5fd → 5.0.0-29788347.3c4e1708

package/3.guide/6.going-further/1.experimental-features.md

@@ -616,6 +616,43 @@ export default defineNuxtConfig({
 })
 ```
 
+## navigateToEarlyReturn
+
+Transform top-level `await navigateTo()` calls in `<script setup>` into an early return from the compiled `setup()` function when the navigation succeeds.
+
+Without this flag, code after `await navigateTo()` continues to run, which can result in later code (including subsequent `navigateTo` calls) overriding the redirect or attempting to render a page with missing data. With this flag enabled, a successful navigation stops execution of the rest of your setup code and the component renders a placeholder comment while the navigation proceeds.
+
+This flag is enabled by default with `compatibilityVersion: 5`, but you can disable it:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    navigateToEarlyReturn: false,
+  },
+})
+```
+
+```vue [pages/example.vue]
+<script setup lang="ts">
+const { data } = await useFetch('/api/data')
+
+if (!data.value) {
+  await navigateTo('/fallback')
+}
+
+// with the flag enabled, this only runs if the navigation did not happen
+const processed = data.value!.map(item => item.name)
+</script>
+```
+
+The transform only applies to top-level `await navigateTo()` statements in `<script setup>` whose result is not used. Calls with the `open` option (or options that cannot be statically analysed) are not transformed, as they should not stop the current page from rendering.
+
+The early return only happens when the navigation succeeds (that is, when `navigateTo` resolves to `undefined`). If the navigation is aborted or fails (for example, blocked by a navigation guard, or navigating to the current route), the rest of your setup code continues to run. On a successful navigation, nothing after the `navigateTo` call runs: this includes `defineExpose` and any lifecycle hook registrations later in `<script setup>`.
+
+::read-more{icon="i-simple-icons-github" to="https://github.com/nuxt/nuxt/issues/23698" target="_blank"}
+See full explanation on the GitHub issue.
+::
+
 ## normalizeComponentNames
 
 Nuxt updates auto-generated Vue component names to match the full component name you would use to auto-import the component.

package/4.api/3.utils/navigate-to.md

@@ -41,6 +41,10 @@ await navigateTo({
 </script>
 ```
 
+::note
+Calling `navigateTo` does not stop execution of the rest of your `<script setup>` code. If you want a successful navigation to return early from `setup()`, enable [`experimental.navigateToEarlyReturn`](/docs/4.x/guide/going-further/experimental-features#navigatetoearlyreturn).
+::
+
 ### Within Route Middleware
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "5.0.0-29787185.8dc3f5fd",
+  "version": "5.0.0-29788347.3c4e1708",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",