@nuxt/docs-nightly 4.5.1-29752449.30d24817 → 4.5.2-2610052030-052d82e

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

@@ -5,7 +5,7 @@ description: "Enable Nuxt experimental features to unlock new possibilities."
 
 Nuxt includes experimental features that you can enable in your configuration file.
 
-Internally, Nuxt uses `@nuxt/schema` to define these experimental features. You can refer to the [API documentation](/docs/4.x/guide/going-further/experimental-features) or the [source code](https://github.com/nuxt/nuxt/blob/main/packages/schema/src/config/experimental.ts) for more information.
+Internally, Nuxt uses `@nuxt/schema` to define these experimental features. You can refer to the [API documentation](/docs/guide/going-further/experimental-features) or the [source code](https://github.com/nuxt/nuxt/blob/main/packages/schema/src/config/experimental.ts) for more information.
 
 ::note
 Note that these features are experimental and could be removed or modified in the future.
@@ -131,7 +131,7 @@ Emits `app:chunkError` hook when there is an error loading vite/webpack chunks.
 
 By default, Nuxt will also perform a reload of the new route when a chunk fails to load when navigating to a new route (`automatic`).
 
-Setting `automatic-immediate` will lead Nuxt to perform a reload of the current route right when a chunk fails to load (instead of waiting for navigation). This is useful for chunk errors that are not triggered by navigation, e.g., when your Nuxt app fails to load a [lazy component](/docs/4.x/directory-structure/app/components#dynamic-imports). A potential downside of this behavior is undesired reloads, e.g., when your app does not need the chunk that caused the error.
+Setting `automatic-immediate` will lead Nuxt to perform a reload of the current route right when a chunk fails to load (instead of waiting for navigation). This is useful for chunk errors that are not triggered by navigation, e.g., when your Nuxt app fails to load a [lazy component](/docs/directory-structure/app/components#dynamic-imports). A potential downside of this behavior is undesired reloads, e.g., when your app does not need the chunk that caused the error.
 
 You can disable automatic handling by setting this to `false`, or handle chunk errors manually by setting it to `manual`.
 
@@ -159,13 +159,13 @@ export default defineNuxtConfig({
 
 ## restoreState
 
-Allows Nuxt app state to be restored from `sessionStorage` when reloading the page after a chunk error or manual [`reloadNuxtApp()`](/docs/4.x/api/utils/reload-nuxt-app) call.
+Allows Nuxt app state to be restored from `sessionStorage` when reloading the page after a chunk error or manual [`reloadNuxtApp()`](/docs/api/utils/reload-nuxt-app) call.
 
 To avoid hydration errors, it will be applied only after the Vue app has been mounted, meaning there may be a flicker on initial load.
 
 ::important
 Consider carefully before enabling this as it can cause unexpected behavior,
-and consider providing explicit keys to [`useState`](/docs/4.x/api/composables/use-state) as auto-generated keys may not match across builds.
+and consider providing explicit keys to [`useState`](/docs/api/composables/use-state) as auto-generated keys may not match across builds.
 ::
 
 ```ts twoslash [nuxt.config.ts]
@@ -178,7 +178,7 @@ export default defineNuxtConfig({
 
 ## inlineRouteRules
 
-Define route rules at the page level using [`defineRouteRules`](/docs/4.x/api/utils/define-route-rules).
+Define route rules at the page level using [`defineRouteRules`](/docs/api/utils/define-route-rules).
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -190,11 +190,11 @@ export default defineNuxtConfig({
 
 Matching route rules will be created, based on the page's `path`.
 
-::read-more{to="/docs/4.x/api/utils/define-route-rules" icon="i-lucide-square-function"}
+::read-more{to="/docs/api/utils/define-route-rules" icon="i-lucide-square-function"}
 Read more in `defineRouteRules` utility.
 ::
 
-:read-more{to="/docs/4.x/guide/concepts/rendering#hybrid-rendering" icon="i-lucide-medal"}
+:read-more{to="/docs/guide/concepts/rendering#hybrid-rendering" icon="i-lucide-medal"}
 
 ## renderJsonPayloads
 
@@ -254,7 +254,7 @@ export default defineNuxtConfig({
 })
 ```
 
-::read-more{to="/docs/4.x/getting-started/prerendering#payload-extraction"}
+::read-more{to="/docs/getting-started/prerendering#payload-extraction"}
 Read more about payload extraction and the consequences of each mode.
 ::
 
@@ -278,9 +278,52 @@ export default defineNuxtConfig({
 })
 ```
 
+## serverPathFallback
+
+Loads a client-side navigation that matches no page route as a full document, so the server can respond with a file in `public/`, a server route, or its 404 page. With this enabled, `<NuxtLink to="/brochure.pdf">` and `<NuxtLink to="/rss.xml">` work on click as they do on a hard load.
+
+A path is never reloaded if the current document was already served for it, so hosts that respond to unknown paths with an SPA fallback render the client-side 404 page.
+
+This flag is enabled by default, but you can disable it:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    serverPathFallback: false,
+  },
+})
+```
+
+The option has no effect when `hashMode` is enabled.
+
+## early404
+
+Responds with an early 404 error for requests whose path cannot match any page route, without loading the Vue app, its plugins or middleware on the server.
+
+Page routes (including aliases) are compiled into a static route matcher at build time, and incoming requests are checked against it before server-side rendering begins. Requests that cannot match any page skip loading the app entirely and go straight to the error page.
+
+Requests without an `Accept: text/html` header (API clients, most scanners) receive a JSON error without loading the app at all, unless `future.compatibilityVersion` is `5`. HTML requests still server-render the error page. A [`cache` route rule](/docs/guide/concepts/rendering#hybrid-rendering) covering the path advertises its `maxAge` as `Cache-Control` on GET/HEAD misses too, letting a CDN absorb repeat requests for unknown paths.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    early404: true,
+  },
+})
+```
+
+::warning
+This is opt-in because it can break apps that rely on runtime routing:
+
+- pages added dynamically with `router.addRoute()` in a plugin. To surface this early, `addRoute` is removed from the type of the router returned by [`useRouter`](/docs/api/composables/use-router) when the option is enabled.
+- route middleware that redirects unknown paths to existing pages
+
+The option is disabled automatically in development, when `hashMode` is enabled, when a root-level catch-all page (such as `pages/[...slug].vue`) matches every path, and when a custom `app/router.options` file may modify `routes` (a file whose default export is a plain object without a `routes` key remains compatible).
+::
+
 ## clientFallback
 
-Enables the experimental [`<NuxtClientFallback>`](/docs/4.x/api/components/nuxt-client-fallback) component for rendering content on the client if there's an error in SSR.
+Enables the experimental [`<NuxtClientFallback>`](/docs/api/components/nuxt-client-fallback) component for rendering content on the client if there's an error in SSR.
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -318,7 +361,7 @@ export default defineNuxtConfig({
 })
 ```
 
-You can also pass an object to configure [view transition types](/docs/4.x/getting-started/transitions#view-transition-types), which allow different CSS animations based on the type of navigation:
+You can also pass an object to configure [view transition types](/docs/getting-started/transitions#view-transition-types), which allow different CSS animations based on the type of navigation:
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -354,7 +397,7 @@ export default defineNuxtConfig({
 
 ## componentIslands
 
-Enables experimental component islands support with [`<NuxtIsland>`](/docs/4.x/api/components/nuxt-island) and `.island.vue` files.
+Enables experimental component islands support with [`<NuxtIsland>`](/docs/api/components/nuxt-island) and `.island.vue` files.
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -364,10 +407,10 @@ export default defineNuxtConfig({
 })
 ```
 
-:read-more{to="/docs/4.x/directory-structure/app/components#server-components"}
+:read-more{to="/docs/guide/concepts/server-components"}
 
 ::note
-Skip `nuxt-client` on non-SFC components such as [`<NuxtLink>`](/docs/4.x/api/components/nuxt-link). See [Client components within server components](/docs/4.x/directory-structure/app/components#client-components-within-server-components).
+Skip `nuxt-client` on non-SFC components such as [`<NuxtLink>`](/docs/api/components/nuxt-link). See [selective hydration with `nuxt-client`](/docs/guide/concepts/server-components#selective-hydration-with-nuxt-client).
 ::
 
 ::read-more{icon="i-simple-icons-github" to="https://github.com/nuxt/nuxt/issues/19772" target="_blank"}
@@ -400,7 +443,7 @@ export default defineNuxtConfig({
 })
 ```
 
-Out of the box, this will enable typed usage of [`navigateTo`](/docs/4.x/api/utils/navigate-to), [`<NuxtLink>`](/docs/4.x/api/components/nuxt-link), [`router.push()`](/docs/4.x/api/composables/use-router) and more.
+Out of the box, this will enable typed usage of [`navigateTo`](/docs/api/utils/navigate-to), [`<NuxtLink>`](/docs/api/components/nuxt-link), [`router.push()`](/docs/api/composables/use-router) and more.
 
 You can even get typed params within a page by using `const route = useRoute('route-name')`.
 
@@ -594,7 +637,36 @@ export default defineNuxtConfig({
 })
 ```
 
-This allows modules to access additional metadata from the page metadata in the build context. If you are using this within a module, it's recommended also to [augment the `NuxtPage` types with your keys](/docs/4.x/directory-structure/app/pages#typing-custom-metadata).
+This allows modules to access additional metadata from the page metadata in the build context. If you are using this within a module, it's recommended also to [augment the `NuxtPage` types with your keys](/docs/directory-structure/app/pages#typing-custom-metadata).
+
+## extractSerializablePageMeta
+
+Enabled by default when `future.compatibilityVersion` is `5` or higher.
+
+By default, Nuxt only reads a fixed list of `definePageMeta()` keys at build time (plus anything in `extraPageMetaExtractionKeys`); everything else is resolved at runtime from a separate module generated per page. With this option, Nuxt writes every JSON-serializable property straight into the generated route record instead.
+
+When every property of a page's `definePageMeta()` can be resolved statically, the route no longer imports that page's meta module at all, which removes one module per page from the dev module graph.
+
+```vue
+<script lang="ts" setup>
+definePageMeta({
+  layout: { name: 'admin', props: { collapsed: true } },
+  title: 'Dashboard',
+})
+</script>
+```
+
+Properties whose values cannot be serialized (functions, variable references, spreads, computed keys) are unaffected and still resolved at runtime.
+
+This has no effect when [`scanPageMeta`](#scanpagemeta) is `false`, as the route record does not override the meta module in that case.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    extractSerializablePageMeta: false,
+  },
+})
+```
 
 ## navigationRepaint
 
@@ -612,6 +684,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.
@@ -742,7 +851,7 @@ export default defineNuxtConfig({
 })
 ```
 
-::read-more{icon="i-simple-icons-github" color="gray" to="/docs/4.x/directory-structure/app/components#delayed-or-lazy-hydration"}
+::read-more{icon="i-simple-icons-github" color="gray" to="/docs/directory-structure/app/components#delayed-or-lazy-hydration"}
 Read more about lazy hydration.
 ::
 
@@ -868,7 +977,7 @@ export default defineNuxtConfig({
 })
 ```
 
-The `useState.resetOnClear` option controls whether [`clearNuxtState`](/docs/4.x/api/utils/clear-nuxt-state) resets state to its initial value (provided by the `init` function of [`useState`](/docs/4.x/api/composables/use-state)) instead of setting it to `undefined`. This defaults to `true` with `compatibilityVersion: 5`.
+The `useState.resetOnClear` option controls whether [`clearNuxtState`](/docs/api/utils/clear-nuxt-state) resets state to its initial value (provided by the `init` function of [`useState`](/docs/api/composables/use-state)) instead of setting it to `undefined`. This defaults to `true` with `compatibilityVersion: 5`.
 
 ## purgeCachedData
 
@@ -892,12 +1001,16 @@ See PR #31379 for implementation details.
 
 ## prefetchPreloadTags
 
-When a `<NuxtLink>` is prefetched and the destination route has [payload extraction](#payloadextraction) enabled (the default for prerendered and cached routes), forward any `<link rel="preload">` hints that the destination set via [`useHead`](/docs/4.x/api/composables/use-head) (or via modules like [`@nuxt/image`](https://image.nuxt.com)'s `<NuxtImg preload>`) into the current document.
+When a `<NuxtLink>` is prefetched and the destination route has [payload extraction](#payloadextraction) enabled (the default for prerendered and cached routes), forward any `<link rel="preload">` hints that the destination set via [`useHead`](/docs/api/composables/use-head) (or via modules like [`@nuxt/image`](https://image.nuxt.com)'s `<NuxtImg preload>`) into the current document.
+
+Forwarded links are downgraded from `rel="preload"` to `rel="prefetch"`, apart from `as="image"` hints, which keep `rel="preload"` with any `fetchpriority` stripped.
 
-The forwarded links are downgraded from `rel="preload"` to `rel="prefetch"` so they don't compete with the current page's critical resources. Only user-defined head tags are forwarded; build-time JS/CSS chunk preloads are already handled separately by the prefetch pipeline.
+Only user-defined head tags are forwarded; build-time JS/CSS chunk preloads are already handled separately by the prefetch pipeline.
 
 This flag is off by default because, combined with `prefetchOn: 'visibility'` (the `<NuxtLink>` default), it could trigger a lot of cross-route prefetches at once. Enable it once you are confident the destination preloads are worth forwarding for the links your users typically encounter.
 
+Chromium and Safari log a `was preloaded using link preload but not used within a few seconds` warning for each forwarded image hint on a route the user never visits. Forwarded image requests also carry no `Purpose: prefetch` header, so they count as ordinary traffic against image CDN quotas, rate limits and analytics.
+
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
@@ -928,6 +1041,20 @@ export default defineNuxtConfig({
 See PR #31373 for implementation details.
 ::
 
+## stripNeverHydratedData
+
+Apply [`serialize: false`](/docs/api/composables/use-async-data#params) by default to `useAsyncData` and `useFetch` calls made within components lazily hydrated with `hydrate-never`, keeping their data out of the `__NUXT_DATA__` payload. Since these components never hydrate on the client, their data is not needed for hydration.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    stripNeverHydratedData: true,
+  },
+})
+```
+
+An explicit `serialize` option always takes precedence. If the same key is shared with components that do hydrate, keep the `serialize` option consistent across calls (Nuxt warns about mismatches in development).
+
 ## headNext
 
 Use head optimisations:
@@ -945,6 +1072,103 @@ export default defineNuxtConfig({
 })
 ```
 
+## routeTypedFetch
+
+Type `$fetch` and `useFetch` from the routes your server builder reports, rather than from the
+responses nitro contributes to `ServerRoutes` through its `InternalApi` interface.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    routeTypedFetch: true,
+  },
+})
+```
+
+The generated route set carries the `body`, `query` and `headers` a handler validates as well as its
+response, typed as it arrives over the wire, so a resolving call is typed more tightly than before:
+
+- a `Date` a handler returns is a `string` at the call site
+- a `body` the handler validates cannot be omitted or given the wrong shape
+- a method the route does not answer is rejected
+- `params` is no longer accepted, since it was only ever an alias for `query`
+- a route you registered by augmenting `ServerRoutes` by hand needs rewriting, as the two
+  descriptions of a route differ (see [the upgrade guide](https://nuxt.com/docs/5.x/getting-started/upgrade#typed-fetch-rebuilt-on-generated-route-types)).
+  A route declared with `Endpoint` (imported from `nuxt/app`) in the rewritten shape is typed
+  with `routeTypedFetch` both on and off, so you can rewrite it ahead of the switch
+
+Because of those, it is opt-in, and `future.compatibilityVersion: 5` enables it. Setting it
+explicitly selects either typing whatever the compatibility version, so you can adopt it before
+moving to Nuxt 5, or move to Nuxt 5 with `routeTypedFetch: false` and adopt it separately.
+
+::note
+This option exists only while both typings are supported. From Nuxt 5 the generated route set is the
+only source and the option is gone.
+::
+
+::note
+While Nuxt 4 runs on nitro v2, nitro declares a global `$fetch` of its own, typed from
+`InternalApi`. Import `$fetch` from `#build/fetch` where you want the generated route types to apply
+to a direct call; `useFetch`, `useLazyFetch` and `useRequestFetch()` are unaffected.
+::
+
+## strictRouteTypes
+
+Reject a request to a path no server route answers. Requires
+[`routeTypedFetch`](#routetypedfetch), which types `$fetch` and `useFetch` from the routes your
+server will serve.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    routeTypedFetch: true,
+    strictRouteTypes: true,
+  },
+})
+```
+
+With `routeTypedFetch` enabled a response is typed by the handler that answers it whatever this
+option is set to. What the option decides is whether a path Nuxt does not recognise is an error or
+is simply typed as `unknown`.
+
+- `false` (default) - a path Nuxt does not recognise is accepted and resolves to `unknown`, and no
+  method is rejected. Nuxt cannot see every way a request may be answered: nitro middleware, a
+  [`routeRules`](/docs/guide/concepts/rendering#hybrid-rendering) proxy or a catch-all handler
+  can answer a path no route describes.
+- `true` - only the routes your server builder reports are accepted, for the methods they answer.
+- `'isomorphic'` - as `true`, and your pages are included as `GET` routes returning `string`, so
+  `$fetch('/about')` is typed by the route the Vue router serves rather than rejected.
+
+With the option on, a typo and a method the route does not answer are both errors:
+
+```ts
+// server/api/todos.post.ts answers POST only
+await $fetch('/api/todos', { method: 'POST' })
+await $fetch('/api/todo', { method: 'POST' })
+//           ^ no POST route matches '/api/todo'
+await $fetch('/api/todos')
+//           ^ no GET route matches '/api/todos'
+```
+
+Two things stay accepted, because they are not Nuxt's to describe: an absolute URL
+(`$fetch('https://example.com')`), and a path built at runtime, which resolves to `unknown` as it
+does with the option off. A `baseURL` is resolved into the path before it is matched, so a request
+made through one is checked against the route it actually asks for. Naming the response type also
+opts a call out, since doing so turns off inference for the request:
+
+```ts
+const data = await $fetch<{ id: string }>(`/api/${resource}`)
+```
+
+::note
+Files in your `public/` directory are not routes your server builder reports, so requesting one
+with `strictRouteTypes` enabled is an error. Fetch those with an explicit response type, or leave
+the option off.
+::
+
+Set this only where your routing is enumerable. An app with a catch-all page under `'isomorphic'`
+matches every path, which is correct but means the option constrains nothing.
+
 ## pendingWhenIdle
 
 `pendingWhenIdle` controls the `pending` ref returned by `useAsyncData` and `useFetch`.
@@ -1037,7 +1261,7 @@ export default defineNuxtConfig({
 The Vite Environment API provides better consistency between development and production builds, more granular control over environment-specific configuration, and improved performance.
 
 ::important
-Enabling this feature changes how Vite plugins are registered and configured. See the [Vite Environment API migration guide](/docs/4.x/getting-started/upgrade#migration-to-vite-environment-api) for details on updating your plugins.
+Enabling this feature changes how Vite plugins are registered and configured. See the [Vite Environment API migration guide](https://nuxt.com/docs/5.x/getting-started/upgrade#migration-to-vite-environment-api) for details on updating your plugins.
 ::
 
 ::read-more{to="https://vite.dev/guide/api-environment" target="_blank"}
@@ -1056,7 +1280,9 @@ export default defineNuxtConfig({
 })
 ```
 
-Streaming is automatically disabled for bot and crawler user agents (such as Googlebot, Bingbot, etc.) to ensure search engines receive fully-rendered HTML for SEO safety. The default pattern matches indexing crawlers only; Lighthouse and other audit tools deliberately fall outside it so synthetic measurements reflect the same streamed response real users get. You can customize the bot detection regex:
+Streaming is automatically disabled for bot and crawler user agents (such as Googlebot, Bingbot, etc.) to ensure search engines receive fully-rendered HTML for SEO safety. The default pattern matches indexing crawlers only; Lighthouse and other audit tools deliberately fall outside it so synthetic measurements reflect the same streamed response real users get.
+
+You can customise which user agents are opted out with `botRegex`. A request whose `user-agent` header matches the pattern is **not** streamed: it receives the fully-rendered, buffered HTML. Requests that do not match are streamed. Setting `botRegex` replaces the default pattern rather than adding to it, so list every crawler you want to keep out of streaming:
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -1086,7 +1312,7 @@ export default defineNuxtConfig({
 
 - `routeRules` setting `noScripts`, `cache`, `isr`, `swr`, `redirect`, or `streaming: false` for the route
 - `ssr: false` routes (already SPA-rendered)
-- Bot/crawler user agents (controlled via `botRegex`)
+- Bot/crawler user agents, that is, requests whose `user-agent` matches `botRegex`
 - Prerendered routes (`nuxt generate`)
 - Server-side `navigateTo()` redirects from plugins, middleware, or page setup
 - Fatal errors thrown during initial render (before the shell flushes)
@@ -1116,6 +1342,12 @@ If an error occurs during streaming after the HTTP status is already committed,
 **Route styles are streamed, JS hints are entry-only.** The shell is flushed before the route renders, so its `<head>` carries entry-chunk styles and hints only. Once render registers the page and layout modules, their CSS is streamed straight after the shell (inlined as `<style>` when `inlineStyles` is enabled, otherwise as stylesheet links), so page, layout, and top-level async-component styles arrive before the body paints (nested async components are a FOUC caveat, covered below). Route-specific JS chunks are not preloaded from the shell; the browser discovers them after parsing the entry script. Streaming improves TTFB on every route; LCP gains are largest on routes whose JS overlaps the entry chunk.
 ::
 
+::warning
+**Head tags registered after the shell flushes become client-side patches.** The renderer waits for the first render pass before flushing the shell, so `useHead`/`useSeoMeta` called synchronously in `<script setup>` (before any `await`), in plugins, or in middleware render into the shell `<head>` as usual. Tags registered later (after an `await` in setup, or inside a nested `<Suspense>` boundary) cannot reach the already-sent `<head>`; they are delivered as inline scripts that patch the DOM on the client.
+
+Clients that run JavaScript apply the patch, and clients matching `botRegex` never stream in the first place, so they receive the full buffered `<head>`. Anything else (a crawler your `botRegex` does not list, a link unfurler, `curl`) will not see those tags at all. JSON-LD scripts, `noscript` tags and body-positioned tags are the exception: they are rendered as real markup before `</body>`, where every client can read them. Keep other SEO-critical tags (canonical links, social meta) synchronous, or opt the route out of streaming with `routeRules: { '/path': { streaming: false } }`.
+::
+
 ::note
 **Component islands are compatible with streaming.** Island slot content and selective-client (`nuxt-client`) components are normally stitched into the HTML in a post-render pass, which is impossible once the body has streamed past the island anchors. Instead, the renderer emits each island teleport as an inert `<template>` at the end of the document and relocates it into place with an inline script that runs before hydration. This is transparent to app code. The exception is apps built with `features.noScripts` and island components, which fall back to the buffered renderer since the relocation script cannot run.
 ::

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

@@ -41,20 +41,56 @@ export default defineNuxtConfig({
 
 ### noScripts
 
-Turn off rendering of Nuxt scripts and JavaScript resource hints. Can also be configured granularly within `routeRules`.
+Turn off rendering of Nuxt scripts and JavaScript resource hints, so pages ship as pure HTML and CSS.
 
-You can also disable scripts more granularly within `routeRules`.
+Possible values:
 
-If set to 'production' or `true`, JavaScript will be disabled in production mode only. If set to 'all', JavaScript will be disabled in both development and production modes.
+- `false` (default): scripts are rendered normally.
+- `'production'` (or `true`, which is normalized to `'production'`): scripts are omitted in production builds only, so hot module replacement and other development features keep working in `nuxt dev`.
+- `'all'`: scripts are omitted in both development and production.
+
+Pages served without scripts navigate with full-page loads. To keep navigation fast, Nuxt emits a [speculation rules](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API) tag on these pages so supporting browsers prefetch and prerender the targets before the user follows a link. The tag is declarative JSON and executes no JavaScript. The rules are scoped to your page routes (which are safe to `GET`) rather than every same-origin link, so a link to a server route such as `/logout` is never speculatively fetched. A catch-all page (for example `pages/[...slug].vue`) matches every path, which widens this back to all same-origin links.
+
+Client-side navigation *to* a route covered by a `noScripts` route rule triggers a full document load instead, so the route is actually served without scripts rather than being rendered by the client-side router. Pages whose routes are known at build time to be covered by such a rule are also excluded from the client bundle entirely.
+
+Scripted pages emit their own speculation rules tag scoped to the `noScripts` route patterns, so browsers can prefetch and prerender those targets before a full-page navigation to them. When view transitions are enabled, these pages also opt into declarative cross-document view transitions to animate the navigation.
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
   features: {
-    noScripts: true, // or 'production' | 'all' | false
+    noScripts: 'production', // or 'all' | false
   },
 })
 ```
 
+You can also disable scripts per-route with the `noScripts` [route rule](/docs/guide/concepts/rendering#hybrid-rendering), which applies in all modes:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  routeRules: {
+    '/blog/**': { noScripts: true },
+  },
+})
+```
+
+When `noScripts` applies to a rendered page, the following are omitted from the HTML:
+
+- the Nuxt entry `<script>` tags
+- the import map for the entry chunk
+- the inlined payload `<script>` (and the payload preload link, when payload extraction is enabled)
+- JavaScript resource hints (`preload` and `prefetch` links for JS chunks)
+
+CSS is unaffected: stylesheet links and inlined styles are still rendered, so the page looks identical. The page simply never hydrates, which means nothing on it is interactive.
+
+A few interactions to be aware of:
+
+- Routes with the `noScripts` route rule are always rendered with the buffered (non-streaming) renderer.
+- [Server components](/docs/guide/concepts/server-components) that only render static HTML work fine, but components hydrated with `nuxt-client` and interactive island slots rely on an inline script to relocate teleported content, so they will not become interactive on a `noScripts` route. When `features.noScripts` is set app-wide and component islands are active, Nuxt also falls back to buffered rendering for this reason.
+
+::read-more{to="/docs/guide/recipes/mostly-static-sites"}
+See the mostly-static site recipe for combining `noScripts` with prerendering, islands and lazy hydration.
+::
+
 ## `future`
 
 There is also a `future` namespace for early opting-in to new features that will become default in a future (possibly major) version of the framework.
@@ -63,7 +99,7 @@ There is also a `future` namespace for early opting-in to new features that will
 
 This enables early access to Nuxt features or flags.
 
-Setting `compatibilityVersion` to `5` changes defaults throughout your Nuxt configuration to opt in to Nuxt v5 behaviour, including enabling the [Vite Environment API](/docs/4.x/guide/going-further/experimental-features#viteenvironmentapi).
+Setting `compatibilityVersion` to `5` changes defaults throughout your Nuxt configuration to opt in to Nuxt v5 behaviour, including enabling the [Vite Environment API](/docs/guide/going-further/experimental-features#viteenvironmentapi).
 
 ```ts
 export default defineNuxtConfig({
@@ -73,7 +109,7 @@ export default defineNuxtConfig({
 })
 ```
 
-::read-more{to="/docs/4.x/getting-started/upgrade#testing-nuxt-5"}
+::read-more{to="/docs/getting-started/upgrade#testing-nuxt-5"}
 Learn more about testing Nuxt 5.
 ::
 

package/3.guide/6.going-further/1.internals.md

@@ -8,15 +8,15 @@ This guide helps you better understand Nuxt internals to develop new solutions a
 
 ## The Nuxt Interface
 
-When you start Nuxt in development mode with [`nuxt dev`](/docs/4.x/api/commands/dev) or building a production application with [`nuxt build`](/docs/4.x/api/commands/build),
+When you start Nuxt in development mode with [`nuxt dev`](/docs/api/commands/dev) or building a production application with [`nuxt build`](/docs/api/commands/build),
 a common context will be created, referred to as `nuxt` internally. It holds normalized options merged with `nuxt.config` file,
-some internal state, and a powerful [hooking system](/docs/4.x/api/advanced/hooks) powered by [unjs/hookable](https://github.com/unjs/hookable)
+some internal state, and a powerful [hooking system](/docs/api/advanced/hooks) powered by [unjs/hookable](https://github.com/unjs/hookable)
 allowing different components to communicate with each other. You can think of it as **Builder Core**.
 
-This context is globally available to be used with [Nuxt Kit](/docs/4.x/guide/going-further/kit) composables.
+This context is globally available to be used with [Nuxt Kit](/docs/guide/going-further/kit) composables.
 Therefore only one instance of Nuxt is allowed to run per process.
 
-To extend the Nuxt interface and hook into different stages of the build process, we can use [Nuxt modules](/docs/4.x/guide/modules).
+To extend the Nuxt interface and hook into different stages of the build process, we can use [Nuxt modules](/docs/guide/modules).
 
 For more details, check out [the source code](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/core/nuxt.ts).
 
@@ -26,14 +26,14 @@ When rendering a page in the browser or on the server, a shared context will be
 This context keeps vue instance, runtime hooks, and internal states like ssrContext and payload for hydration.
 You can think of it as **Runtime Core**.
 
-This context can be accessed using [`useNuxtApp()`](/docs/4.x/api/composables/use-nuxt-app) composable within Nuxt plugins and `<script setup>` and vue composables.
+This context can be accessed using [`useNuxtApp()`](/docs/api/composables/use-nuxt-app) composable within Nuxt plugins and `<script setup>` and vue composables.
 Global usage is possible for the browser but not on the server, to avoid sharing context between users.
 
-Since [`useNuxtApp`](/docs/4.x/api/composables/use-nuxt-app) throws an exception if context is currently unavailable, if your composable does not always require `nuxtApp`, you can use [`tryUseNuxtApp`](/docs/4.x/api/composables/use-nuxt-app#tryusenuxtapp) instead, which will return `null` instead of throwing an exception.
+Since [`useNuxtApp`](/docs/api/composables/use-nuxt-app) throws an exception if context is currently unavailable, if your composable does not always require `nuxtApp`, you can use [`tryUseNuxtApp`](/docs/api/composables/use-nuxt-app#tryusenuxtapp) instead, which will return `null` instead of throwing an exception.
 
-To extend the `nuxtApp` interface and hook into different stages or access contexts, we can use [Nuxt Plugins](/docs/4.x/directory-structure/app/plugins).
+To extend the `nuxtApp` interface and hook into different stages or access contexts, we can use [Nuxt Plugins](/docs/directory-structure/app/plugins).
 
-Check [Nuxt App](/docs/4.x/api/composables/use-nuxt-app) for more information about this interface.
+Check [Nuxt App](/docs/api/composables/use-nuxt-app) for more information about this interface.
 
 `nuxtApp` has the following properties:
 
@@ -77,6 +77,6 @@ Nuxt builds and bundles project using Node.js but also has a runtime side.
 
 While both areas can be extended, that runtime context is isolated from build-time. Therefore, they are not supposed to share state, code, or context other than runtime configuration!
 
-`nuxt.config` and [Nuxt modules](/docs/4.x/guide/modules) can be used to extend the build context, and [Nuxt Plugins](/docs/4.x/directory-structure/app/plugins) can be used to extend runtime.
+`nuxt.config` and [Nuxt modules](/docs/guide/modules) can be used to extend the build context, and [Nuxt Plugins](/docs/directory-structure/app/plugins) can be used to extend runtime.
 
-When building an application for production, `nuxt build` will generate a standalone build in the `.output` directory, independent of `nuxt.config` and [Nuxt modules](/docs/4.x/guide/modules).
+When building an application for production, `nuxt build` will generate a standalone build in the `.output` directory, independent of `nuxt.config` and [Nuxt modules](/docs/guide/modules).