@nuxt/docs-nightly 5.0.0-29753050.bc11b4f9 → 5.0.0-29753113.aaeaed06

package/1.getting-started/01.introduction.md

@@ -48,9 +48,9 @@ disable SSR globally with the `ssr: false` option or leverage hybrid rendering b
 
 ### Server engine
 
-The Nuxt server engine [Nitro](https://nitro.build/) unlocks new full-stack capabilities.
+The Nuxt server engine, [Nitro](https://nitro.build/), unlocks new full-stack capabilities.
 
-In development, it uses Rollup and Node.js workers for your server code and context isolation. It also generates your server API by reading files in `server/api/` and server middleware from `server/middleware/`.
+In development, it uses Rollup and Node.js workers for your server code and context isolation. It also generates your server API by reading files from `server/api/` and server middleware from `server/middleware/`.
 
 In production, Nitro builds your app and server into one universal `.output` directory. This output is light: minified and removed from any Node.js modules (except polyfills). You can deploy this output on any system supporting JavaScript, from Node.js, Serverless, Workers, Edge-side rendering or purely static.
 

package/2.directory-structure/1.app/1.components.md

@@ -486,17 +486,7 @@ Standalone server components will always be rendered on the server, also known a
 
 When their props update, this will result in a network request that will update the rendered HTML in-place.
 
-Server components are currently experimental and in order to use them, you need to enable the 'component islands' feature in your nuxt.config:
-
-```ts twoslash [nuxt.config.ts]
-export default defineNuxtConfig({
-  experimental: {
-    componentIslands: true,
-  },
-})
-```
-
-Now you can register server-only components with the `.server` suffix and use them anywhere in your application automatically.
+Register server-only components with the `.server` suffix and use them anywhere in your application automatically.
 
 ```bash [Directory Structure]
 -| components/
@@ -521,96 +511,8 @@ Server-only components use [`<NuxtIsland>`](/docs/4.x/api/components/nuxt-island
 Server components (and islands) must have a single root element. (HTML comments are considered elements as well.)
 ::
 
-::warning
-Props are passed to server components via URL query parameters, and are therefore limited by the possible length of a URL, so be careful not to pass enormous amounts of data to server components via props.
-::
-
-::note
-Server component props come from the request (URL query or body), so treat them as untrusted input. Nuxt rejects the props most likely to leak through unintentionally: a top-level `as` that the island does not declare (an undeclared prop falls through as an attribute onto the island's root), and, with `vue.runtimeCompiler` enabled, a `template` anywhere in the props. Beyond that, avoid feeding props you have not validated into dynamic component resolution (`<component :is>`{lang=vue}, `h()`, `resolveDynamicComponent()`, or a polymorphic `as` / `asChild` prop), since a string can resolve to any registered component or HTML element.
-
-Props a component does not declare fall through as attributes onto its single root element, so an island whose root is a polymorphic component (e.g. from `reka-ui` / `@nuxt/ui`) can receive attributes you did not bind. Set `defineOptions({ inheritAttrs: false })`{lang=ts} on such islands, or declare the props you accept.
-
-To switch components based on caller input, map a discriminator through an allowlist of imported components rather than passing the raw prop:
-
-```vue
-<script setup lang="ts">
-import type { Component } from 'vue'
-import CardA from './CardA.vue'
-import CardB from './CardB.vue'
-
-const props = defineProps<{ variant: string }>()
-const allowed: Record<string, Component> = { a: CardA, b: CardB }
-const component = allowed[props.variant] ?? CardA
-</script>
-
-<template>
-  <component :is="component" />
-</template>
-```
-::
-
-::warning
-Be careful when nesting islands within other islands as each island adds some extra overhead.
-::
-
-::warning
-Most features for server-only components and island components, such as slots and client components, are only available for single file components.
-::
-
-#### Client components within server components
-
-::note
-This feature needs `experimental.componentIslands.selectiveClient` within your configuration to be true.
-::
-
-You can partially hydrate a component by setting a `nuxt-client` attribute on the component you wish to be loaded client-side.
-
-```vue [app/components/ServerWithClient.vue]
-<template>
-  <div>
-    <HighlightedMarkdown markdown="# Headline" />
-    <!-- Counter will be loaded and hydrated client-side -->
-    <Counter
-      nuxt-client
-      :count="5"
-    />
-  </div>
-</template>
-```
-
-::note
-This only works within a server component. Slots for client components are working only with `experimental.componentIsland.selectiveClient` set to `'deep'` and since they are rendered server-side, they are not interactive once client-side.
-::
-
-::warning
-Use `nuxt-client` only on local `.vue` SFCs. Built-ins like [`<NuxtLink>`](/docs/4.x/api/components/nuxt-link) skip the islands transform. After client navigation you may see `Failed to locate Teleport target`, or the link disappears with no error. Wrap the built-in in your own `.vue` file and put `nuxt-client` on that wrapper, or drop `nuxt-client` from the built-in. See [#29251](https://github.com/nuxt/nuxt/issues/29251) and [#26002](https://github.com/nuxt/nuxt/issues/26002).
-::
-
-#### Server Component Context
-
-When rendering a server-only or island component, `<NuxtIsland>` makes a fetch request which comes back with a `NuxtIslandResponse`. (This is an internal request if rendered on the server, or a request that you can see in the network tab if it's rendering on client-side navigation.)
-
-This means:
-
-* A new Vue app will be created server-side to create the `NuxtIslandResponse`.
-* A new 'island context' will be created while rendering the component.
-* You can't access the 'island context' from the rest of your app and you can't access the context of the rest of your app from the island component. In other words, the server component or island is _isolated_ from the rest of your app.
-* Your plugins will run again when rendering the island, unless they have `env: { islands: false }` set (which you can do in an object-syntax plugin).
-
-::important
-Route middleware does not run when rendering island components. Middleware is a routing concept that applies to pages, not components, and is not designed to control component rendering.
-::
-
-::important
-`useRoute()` and other `vue-router` composables do not track the current page route inside a server (island) component. The island is rendered in its own isolated Vue app keyed only on its props (and any explicit context), which is what keeps islands cacheable independently of the page they are rendered on. Inside an island, `useRoute()` will reflect the island's own request, not the page the user is on.
-
-If an island needs information about the current route, pass it in explicitly &mdash; either as props from the parent component, or via the `context` prop on `<NuxtIsland>` (read inside the island from `nuxtApp.ssrContext.islandContext`).
-::
-
-Within an island component, you can access its island context through `nuxtApp.ssrContext.islandContext`. Note that while island components are still marked as experimental, the format of this context may change.
-
-::note
-Slots can be interactive and are wrapped within a `<div>` with `display: contents;`
+::read-more{to="/docs/4.x/guide/concepts/server-components"}
+Read more about how islands are rendered, the isolated island context, selective hydration with `nuxt-client`, slots, caching and current limitations in the dedicated server components guide.
 ::
 
 ### Paired with a Client component

package/3.guide/1.concepts/1.rendering.md

@@ -197,7 +197,7 @@ The different properties you can use are the following:
 - `swr: number | boolean`{lang=ts} - Add cache headers to the server response and cache it on the server or reverse proxy for a configurable TTL (time to live). The `node-server` preset of Nitro is able to cache the full response. When the TTL expired, the cached response will be sent while the page will be regenerated in the background. If true is used, a `stale-while-revalidate` header is added without a MaxAge.
 - `isr: number | boolean`{lang=ts} - The behavior is the same as `swr` except that we are able to add the response to the CDN cache on platforms that support this (currently Netlify or Vercel). If `true` is used, the content persists until the next deploy inside the CDN.
 - `prerender: boolean`{lang=ts} - Prerenders routes at build time and includes them in your build as static assets
-- `noScripts: boolean`{lang=ts} - Disables rendering of Nuxt scripts and JS resource hints for sections of your site.
+- `noScripts: boolean`{lang=ts} - Disables rendering of Nuxt scripts and JS resource hints for sections of your site. Read more about [`noScripts`](/docs/4.x/guide/going-further/features#noscripts).
 - `appMiddleware: string | string[] | Record<string, boolean>`{lang=ts} - Allows you to define middleware that should or should not run for page paths within the Vue app part of your application (that is, not your Nitro routes)
 
 ::note

package/3.guide/1.concepts/6.server-components.md

@@ -0,0 +1,193 @@
+---
+title: 'Server Components'
+description: Render individual components on the server only, keeping their JavaScript out of your client bundle.
+---
+
+Nuxt renders your app on the server by default, but then it ships the JavaScript for every component to the browser and hydrates the whole page. For content-heavy components (markdown rendering, syntax highlighting, CMS output) that never change on the client, this is wasted work: the user downloads, parses and executes code whose only job is to reproduce HTML that is already on the page.
+
+Server components (also called island components) invert this. A server component is rendered on the server, its HTML is embedded in the page, and none of its JavaScript is sent to the client. Its dependencies (a markdown parser, a highlighting library) stay on the server too.
+
+::tip{icon="i-lucide-newspaper" to="https://roe.dev/blog/nuxt-server-components" target="_blank"}
+Read Daniel Roe's guide to Nuxt Server Components.
+::
+
+:video-accordion{title="Watch Learn Vue video about Nuxt Server Components" videoId="u1yyXe86xJM"}
+
+## Enabling Server Components
+
+Component islands are controlled by [`experimental.componentIslands`](/docs/4.x/guide/going-further/experimental-features#componentislands). The default value is `'auto'`, which enables the feature automatically as soon as your app contains a server component or island, so in most cases you do not need any configuration.
+
+Set the option explicitly if you want remote islands or selective client hydration:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    componentIslands: {
+      selectiveClient: true, // or 'deep', to enable `nuxt-client`
+      remoteIsland: false, // allow rendering islands from a remote source
+    },
+  },
+})
+```
+
+::read-more{icon="i-simple-icons-github" to="https://github.com/nuxt/nuxt/issues/19772" target="_blank"}
+Server components are still marked experimental. You can follow the roadmap on GitHub.
+::
+
+## `.server.vue` Components
+
+Add the `.server` suffix to a component to make it a standalone server component:
+
+```bash [Directory Structure]
+-| app/
+---| components/
+-----| HighlightedMarkdown.server.vue
+```
+
+Use it like any other component:
+
+```vue [app/pages/example.vue]
+<template>
+  <div>
+    <!--
+      rendered on the server; the markdown parsing and highlighting
+      libraries are not included in your client bundle
+     -->
+    <HighlightedMarkdown markdown="# Headline" />
+  </div>
+</template>
+```
+
+Components inside `~/components/islands/` are also registered as islands and can be rendered with [`<NuxtIsland>`](/docs/4.x/api/components/nuxt-island) directly, for example `<NuxtIsland name="MyIsland" />` for `~/components/islands/MyIsland.vue`.
+
+You can also pair a `.server.vue` component with a `.client.vue` component of the same name for [separate server and client implementations](/docs/4.x/directory-structure/app/components#paired-with-a-client-component). In that case the component is not an island: the client half hydrates normally.
+
+::warning
+Server components (and islands) must have a single root element. (HTML comments are considered elements as well.)
+::
+
+## How Islands Are Rendered
+
+Server components use [`<NuxtIsland>`](/docs/4.x/api/components/nuxt-island) under the hood. Rendering an island issues a request to a dedicated island endpoint, which:
+
+- creates a **new, isolated Vue app** on the server to render just that component
+- creates an 'island context' that you can access via `nuxtApp.ssrContext.islandContext` inside the island
+- runs your plugins again, unless they set `env: { islands: false }` (object-syntax plugins)
+
+Because the island is isolated from the rest of your app:
+
+- you cannot share state (provide/inject, Pinia, `useState`) between the page and the island; pass data via props instead
+- [`useRoute()`](/docs/4.x/api/composables/use-route) inside an island reflects the island's own request, not the page the user is on. If an island needs route information, pass it in explicitly, either as props or via the `context` prop on `<NuxtIsland>` (read inside the island from `nuxtApp.ssrContext.islandContext`)
+- route middleware does not run when rendering islands
+
+Props are serialized and sent as **GET query parameters**. This makes island responses cacheable, but it also means:
+
+- props must be JSON-serializable
+- props are limited by URL length, so avoid passing large amounts of data
+- props may be visible in server access logs, CDN caches and `Referer` headers
+
+::note
+Because props come from the request (URL query or body), treat them as untrusted input. Nuxt rejects the props most likely to leak through unintentionally: a top-level `as` that the island does not declare (an undeclared prop falls through as an attribute onto the island's root), and, with `vue.runtimeCompiler` enabled, a `template` anywhere in the props. Beyond that, avoid feeding props you have not validated into dynamic component resolution (`<component :is>`{lang=vue}, `h()`, `resolveDynamicComponent()`, or a polymorphic `as` / `asChild` prop), since a string can resolve to any registered component or HTML element.
+
+Props a component does not declare fall through as attributes onto its single root element, so an island whose root is a polymorphic component (e.g. from `reka-ui` / `@nuxt/ui`) can receive attributes you did not bind. Set `defineOptions({ inheritAttrs: false })`{lang=ts} on such islands, or declare the props you accept.
+
+To switch components based on caller input, map a discriminator through an allowlist of imported components rather than passing the raw prop:
+
+```vue
+<script setup lang="ts">
+import type { Component } from 'vue'
+import CardA from './CardA.vue'
+import CardB from './CardB.vue'
+
+const props = defineProps<{ variant: string }>()
+const allowed: Record<string, Component> = { a: CardA, b: CardB }
+const component = allowed[props.variant] ?? CardA
+</script>
+
+<template>
+  <component :is="component" />
+</template>
+```
+::
+
+Changing an island's props triggers a network request that re-renders the component on the server and updates its HTML in place.
+
+::read-more{to="/docs/4.x/api/components/nuxt-island"}
+Read the full `<NuxtIsland>` API documentation, including props, slots, events and known limitations.
+::
+
+## Selective Hydration with `nuxt-client`
+
+An island is static by default, but you can hydrate individual components inside it by adding the `nuxt-client` attribute. This requires `experimental.componentIslands.selectiveClient` to be enabled.
+
+```vue [app/components/ServerWithClient.server.vue]
+<template>
+  <div>
+    <HighlightedMarkdown markdown="# Headline" />
+    <!-- Counter will be loaded and hydrated client-side -->
+    <Counter
+      nuxt-client
+      :count="5"
+    />
+  </div>
+</template>
+```
+
+The component marked with `nuxt-client` is server-rendered as part of the island, then hydrated by the main client app. Only its chunk is shipped to the client; the rest of the island remains static.
+
+Setting `selectiveClient: 'deep'` additionally allows passing slots to `nuxt-client` components. Those slots are rendered on the server and are **not interactive** on the client.
+
+::warning
+Use `nuxt-client` only on local `.vue` SFCs. Built-ins like [`<NuxtLink>`](/docs/4.x/api/components/nuxt-link) skip the islands transform. After client navigation you may see `Failed to locate Teleport target`, or the link disappears with no error. Wrap the built-in in your own `.vue` file and put `nuxt-client` on that wrapper. See [#29251](https://github.com/nuxt/nuxt/issues/29251) and [#26002](https://github.com/nuxt/nuxt/issues/26002).
+::
+
+## Slots
+
+Slots can be passed to an island component if declared in the island. Slot content is provided by the parent, so it belongs to the main client app and **is** interactive (it is wrapped in a `<div>` with `display: contents;`).
+
+`<NuxtIsland>` reserves the `#fallback` slot to specify content rendered before the island loads (when `lazy` is set) or when fetching the island fails.
+
+## The Client Navigation Round Trip
+
+On the initial server-rendered page load, islands are rendered inline and there is no extra request. On **client-side navigation**, however, each island on the destination page must be fetched from the server (you can see these requests in the network tab). This has real costs:
+
+- islands block on a network round trip during navigation, unless you pass the `lazy` prop (with a `#fallback` slot) to render them non-blockingly
+- an app with many islands per page makes many requests per navigation
+
+Islands work best on pages that are reached by full page loads (content and marketing pages) or when their number per page is small. If a component needs to update frequently on the client, an island is probably the wrong tool.
+
+## Prerendering and Caching
+
+Islands play well with static and cached rendering:
+
+- during prerendering (`nuxt generate` or `prerender` route rules), island responses are cached, so identical islands (same name, props and context) are rendered once and reused
+- because props travel as GET query parameters, island responses can also be cached by your server or CDN at the island endpoint level
+- two instances of the same island with the same props share a single server render and payload entry
+
+Note that island responses being keyed only on name, props and context is exactly what keeps them cacheable independently of the page they appear on; this is also why they cannot see the current route (see above).
+
+If you are building a mostly-static site, islands combine well with `prerender` and `noScripts` route rules.
+
+::read-more{to="/docs/4.x/guide/recipes/mostly-static-sites"}
+See the mostly-static site recipe for combining prerendering, `noScripts`, islands and lazy hydration.
+::
+
+One interaction to be aware of: island slots and `nuxt-client` components rely on a small inline script to relocate teleported content into place before hydration. On routes rendered with [`noScripts`](/docs/4.x/guide/going-further/features#noscripts), that script is omitted, so fully interactive `nuxt-client` components will not hydrate there. Plain static islands are unaffected.
+
+## Current Limitations
+
+Server components are experimental, and some rough edges are tracked in open issues:
+
+- Most features for server-only and island components, such as slots and `nuxt-client` components, are only available for single file components.
+- Global styles of your application are sent with each island response, and island assets can be loaded twice in some setups ([#29591](https://github.com/nuxt/nuxt/issues/29591)).
+- Using islands can significantly increase the number of chunks generated at build time ([#34855](https://github.com/nuxt/nuxt/issues/34855)).
+- `:slotted()` styles are ignored in server component slots ([#31510](https://github.com/nuxt/nuxt/issues/31510)).
+- Template refs cannot reference elements inside a server component from the parent ([#31512](https://github.com/nuxt/nuxt/issues/31512)).
+- `inject`/`provide` does not cross the island boundary, so injecting from the page into a standalone server component does not work ([#22751](https://github.com/nuxt/nuxt/issues/22751)).
+- Server components rendered via the auto-generated wrapper do not expose load and error events; use `<NuxtIsland>` directly if you need its `error` event and `refresh()` method ([#25744](https://github.com/nuxt/nuxt/issues/25744)).
+- [`useId`](https://vuejs.org/api/composition-api-helpers#useid) has known limitations inside islands; see the [`<NuxtIsland>` documentation](/docs/4.x/api/components/nuxt-island#known-limitations).
+- Each nested island adds extra overhead, so be careful when nesting islands within other islands.
+
+::read-more{to="/docs/4.x/directory-structure/app/components#server-components"}
+Read more about server component file conventions in the components directory documentation.
+::

package/3.guide/2.best-practices/performance.md

@@ -111,6 +111,10 @@ To optimize your app, you may want to delay the hydration of some components unt
 
 :read-more{title="Lazy hydration" to="/docs/4.x/directory-structure/app/components#delayed-or-lazy-hydration"}
 
+For content and marketing sites that need little or no client-side interactivity, you can go further and combine prerendering, the `noScripts` route rule, [server components](/docs/4.x/guide/concepts/server-components) and lazy hydration to ship near-zero JavaScript.
+
+:read-more{title="Mostly-static sites" to="/docs/4.x/guide/recipes/mostly-static-sites"}
+
 ### Fetching data
 
 To avoid fetching same data twice (once on the server and once on client) Nuxt provides [`useFetch`](/docs/4.x/api/composables/use-fetch) and [`useAsyncData`](/docs/4.x/api/composables/use-async-data). They ensure that if an API call is made on the server, the data is forwarded to the client in the payload instead of being fetched again.

package/3.guide/5.recipes/5.mostly-static-sites.md

@@ -0,0 +1,109 @@
+---
+title: 'Mostly-Static Sites'
+description: 'Ship near-zero JavaScript for content and marketing sites while keeping islands of interactivity.'
+---
+
+By default, Nuxt server-renders a page and then hydrates all of it. For a page that is 95% static text and images, that hydration JavaScript is mostly overhead: it delays interactivity and competes with your content for bandwidth and CPU, which can hurt metrics like mobile PageSpeed scores.
+
+Nuxt has the pieces to avoid paying that cost where you don't need it. This recipe combines them:
+
+1. **Prerender** your content routes at build time.
+2. **Drop the scripts** on those routes with the `noScripts` route rule.
+3. Use **server components** for widgets that need server rendering but no interactivity.
+4. Use **lazy hydration** on routes that keep their scripts, so interactivity is paid for only when needed.
+
+## Prerender and Drop Scripts
+
+For routes that have no client-side interactivity at all, combine `prerender` and `noScripts` in [`routeRules`](/docs/4.x/guide/concepts/rendering#hybrid-rendering):
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  routeRules: {
+    '/blog/**': { prerender: true, noScripts: true },
+    '/about': { prerender: true, noScripts: true },
+  },
+})
+```
+
+These routes are rendered to plain HTML at build time, and the rendered pages omit the Nuxt entry scripts, import map, payload script and JS resource hints. CSS is still included. The result is a page with effectively zero JavaScript cost.
+
+::read-more{to="/docs/4.x/guide/going-further/features#noscripts"}
+Read more about exactly what `noScripts` omits, and the app-wide `features.noScripts` option.
+::
+
+::important
+A `noScripts` page does not hydrate. Nothing on it is interactive: no `@click` handlers, no `<NuxtLink>` prefetching (links still work as plain `<a>` tags), no client-side navigation away from the page. Only use it on routes where that is what you want.
+::
+
+## Islands for Server-Rendered Widgets
+
+Some parts of a static page still benefit from being components with real logic behind them: rendered markdown, syntax-highlighted code, CMS content. Use [server components](/docs/4.x/guide/concepts/server-components) for these. They render on the server, and their dependencies never reach the client bundle:
+
+```bash [Directory Structure]
+-| app/
+---| components/
+-----| HighlightedMarkdown.server.vue
+```
+
+```vue [app/pages/blog/[slug\\].vue]
+<template>
+  <article>
+    <h1>{{ post.title }}</h1>
+    <HighlightedMarkdown :markdown="post.body" />
+  </article>
+</template>
+```
+
+Static islands like this work fine on `noScripts` routes, since their HTML is embedded at render time.
+
+::warning
+Fully interactive widgets inside islands (components marked with [`nuxt-client`](/docs/4.x/guide/concepts/server-components#selective-hydration-with-nuxt-client), or interactive island slots) do **not** work on a `noScripts` route. Island teleports are relocated into place by a small inline script before hydration; with scripts disabled, that relocation cannot run and nothing hydrates. If a page needs even one interactive widget, keep scripts on that route and use lazy hydration instead.
+::
+
+## Lazy Hydration for the Rest
+
+For routes that need some interactivity, keep scripts enabled but control *when* components hydrate using [lazy hydration](/docs/4.x/directory-structure/app/components#delayed-or-lazy-hydration):
+
+```vue [app/pages/index.vue]
+<template>
+  <div>
+    <HeroSection />
+    <!-- static content that never needs to become interactive -->
+    <LazyTestimonials hydrate-never />
+    <!-- hydrate only when scrolled into view -->
+    <LazyNewsletterSignup hydrate-on-visible />
+    <!-- hydrate when the browser is idle -->
+    <LazyCookieBanner hydrate-on-idle />
+  </div>
+</template>
+```
+
+`hydrate-never` is particularly useful on content sites: the component's HTML is server-rendered, but it is never hydrated, so its JavaScript is never executed (though prop changes will still trigger hydration).
+
+## Putting It Together
+
+A typical mostly-static site ends up with:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  routeRules: {
+    // pure content: prerendered, zero JS
+    '/': { prerender: true, noScripts: true },
+    '/blog/**': { prerender: true, noScripts: true },
+    // pages with an interactive widget: prerendered, scripts kept
+    '/contact': { prerender: true },
+  },
+})
+```
+
+- content routes ship plain HTML and CSS
+- islands (`.server.vue` components) handle server-rendered widgets everywhere, keeping heavy dependencies out of the client bundle
+- the few interactive routes keep scripts, with `hydrate-on-visible` / `hydrate-on-idle` / `hydrate-never` limiting how much work the browser does up front
+
+::read-more{to="/docs/4.x/getting-started/prerendering"}
+Read more about prerendering, including selective prerendering and payload extraction.
+::
+
+::read-more{to="/docs/4.x/guide/best-practices/performance"}
+Read more general performance best practices for Nuxt apps.
+::

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

@@ -332,10 +332,10 @@ export default defineNuxtConfig({
 })
 ```
 
-:read-more{to="/docs/4.x/directory-structure/app/components#server-components"}
+:read-more{to="/docs/4.x/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/4.x/api/components/nuxt-link). See [selective hydration with `nuxt-client`](/docs/4.x/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"}
@@ -896,6 +896,20 @@ export default defineNuxtConfig({
 See PR #31373 for implementation details.
 ::
 
+## stripNeverHydratedData
+
+Apply [`serialize: false`](/docs/4.x/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:

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

@@ -41,20 +41,50 @@ 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.
 
 ```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/4.x/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/4.x/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/4.x/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.

package/4.api/1.components/8.nuxt-island.md

@@ -20,6 +20,10 @@ Global styles of your application are sent with the response.
 Server only components use `<NuxtIsland>` under the hood
 ::
 
+::read-more{to="/docs/4.x/guide/concepts/server-components"}
+Read the dedicated guide to server components and islands.
+::
+
 ## Props
 
 - `name` : Name of the component to render.
@@ -75,7 +79,7 @@ export default defineNuxtPlugin((nuxtApp) => {
 
 - **Identical islands still share the same ids.** Two instances of the same island rendered with the same name, props and context share a single server render (and payload entry), so their HTML — including any `useId`-generated ids — is identical, and the island context id used as prefix is the same. This results in duplicated `id` attributes in the DOM, which can break `aria-*` references and `<label for>` associations between the two instances. There is currently no workaround for this case.
 
-- **`useId` does not work in interactive components inside islands.** A component loaded with the [`nuxt-client` attribute](/docs/4.x/directory-structure/app/components#client-components-within-server-components) is server-rendered inside the island's app but hydrated by the main client app, so `useId` returns different values on the server and on the client, causing a hydration mismatch.
+- **`useId` does not work in interactive components inside islands.** A component loaded with the [`nuxt-client` attribute](/docs/4.x/guide/concepts/server-components#selective-hydration-with-nuxt-client) is server-rendered inside the island's app but hydrated by the main client app, so `useId` returns different values on the server and on the client, causing a hydration mismatch.
 
 ## Slots
 

package/4.api/2.composables/use-async-data.md

@@ -167,6 +167,7 @@ type AsyncDataOptions<ResT, DataT = ResT> = {
   getCachedData?: (key: string, nuxtApp: NuxtApp, ctx: AsyncDataRequestContext) => DataT | undefined
   timeout?: number
   enabled?: MaybeRefOrGetter<boolean>
+  serialize?: boolean
 }
 
 type AsyncDataRequestContext = {
@@ -218,6 +219,7 @@ The `handler` function should be **side-effect free** to ensure predictable beha
 | `deep` :badge[v3.8]{color="info" size="xs" class="align-middle"}          | `boolean`                                   | `false`    | Return data in a deep ref object. Defaults to `false` for improved performance (shallow ref object).                                                                                                                                                                                 |
 | `dedupe` :badge[v3.9]{color="info" size="xs" class="align-middle"}        | `'cancel' \| 'defer'`                       | `'cancel'` | Policy when triggering an execution more than once at a time.                                                                                                                                                                                                                        |
 | `enabled` :badge[v4.5]{color="info" size="xs" class="align-middle"}       | `boolean`                                   | `true`     | Barrier that gates whether the `handler` may run. While `false`, every execution is blocked (initial fetch, `execute`/`refresh`, and watch triggers), and switching `true` → `false` cancels any in-flight request without clearing `data`. Re-enabling does not refetch on its own. |
+| `serialize` :badge[v4.6]{color="info" size="xs" class="align-middle"}     | `boolean`                                   | `true`     | Whether to store resolved data in the Nuxt payload (`__NUXT_DATA__`). When `false`, server-fetched data is kept out of the payload and the client will refetch after hydration if a component renders it. Pair with [lazy hydration](/docs/4.x/guide/best-practices/performance#lazy-hydration) to avoid hydration mismatches and unnecessary client fetches. |
 
 ::note
 All options can be given a `computed` or `ref` value. These will be watched and new requests made automatically with any new values if they are updated.
@@ -261,6 +263,7 @@ The following options **can differ** without triggering warnings:
 - `dedupe`
 - `watch`
 - `enabled`
+- `serialize`
 
 ```ts [app/pages/index.vue]
 // ❌ This will trigger a development warning

package/4.api/2.composables/use-fetch.md

@@ -170,6 +170,7 @@ type UseFetchOptions<ResT, DataT = ResT> = {
   dedupe?: 'cancel' | 'defer'
   timeout?: number
   enabled?: MaybeRefOrGetter<boolean>
+  serialize?: boolean
   default?: () => DataT | Ref<DataT>
   transform?: (input: ResT) => DataT | Promise<DataT>
   pick?: string[]
@@ -229,6 +230,7 @@ type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'
 | `deep` :badge[v3.8]{color="info" size="xs" class="align-middle"}          | `boolean`                                                               | `false`    | Return data in a deep ref object. Defaults to `false` for improved performance (shallow ref object).                                                                                                                                                                               |
 | `dedupe` :badge[v3.9]{color="info" size="xs" class="align-middle"}        | `'cancel' \| 'defer'`                                                   | `'cancel'` | Avoid fetching same key more than once at a time.                                                                                                                                                                                                                                  |
 | `enabled` :badge[v4.5]{color="info" size="xs" class="align-middle"}       | `boolean`                                                               | `true`     | Barrier that gates whether the request may run. While `false`, every execution is blocked (initial fetch, `execute`/`refresh`, and watch triggers), and switching `true` → `false` cancels any in-flight request without clearing `data`. Re-enabling does not refetch on its own. |
+| `serialize` :badge[v4.6]{color="info" size="xs" class="align-middle"}     | `boolean`                                                               | `true`     | Whether to store resolved data in the Nuxt payload (`__NUXT_DATA__`). When `false`, server-fetched data is kept out of the payload and the client will refetch after hydration if a component renders it. Pair with [lazy hydration](/docs/4.x/guide/best-practices/performance#lazy-hydration) to avoid hydration mismatches and unnecessary client fetches. |
 | `$fetch` :badge[v3.2]{color="info" size="xs" class="align-middle"}        | `typeof globalThis.$fetch`                                              | -          | Custom $fetch implementation. See [Custom useFetch in Nuxt](/docs/4.x/guide/recipes/custom-usefetch)                                                                                                                                                                               |
 
 ::note

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "5.0.0-29753050.bc11b4f9",
+  "version": "5.0.0-29753113.aaeaed06",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",