@nuxt/docs-nightly 4.5.2-29756973.d1e6ba2e → 4.5.2-29757143.58d8fcc3

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/1.getting-started/17.testing.md

@@ -734,6 +734,13 @@ Please use the options below for the `setup` method.
   - Type: `'vitest' | 'jest' | 'cucumber'`
   - Default: `'vitest'`
 
+- `logLevel`: Overrides the consola log level for the server subprocess. (use NUXT_TEST_LOG_LEVEL environment variable to override)
+  - Type: `number`
+  - Default: `1`
+- `captureServerLogs`: Whether to capture server process output instead of inheriting stdio. When `true` (default), server stdout/stderr is suppressed from the console and accessible via `getServerLogs()`. Set to `false` to restore the old inherit-stdio behaviour (useful when debugging a test locally).
+  - Type: `boolean`
+  - Default: `true`
+
 ##### Target `host` end-to-end example
 
 A common use-case for end-to-end testing is running the tests against a deployed application running in the same environment typically used for Production.
@@ -793,6 +800,27 @@ const pageUrl = url('/page')
 // 'http://localhost:6840/page'
 ```
 
+#### `getServerLogs()`
+
+Returns the lines captured from the server subprocess's stdout/stderr since the last `startServer()` call (or `clearServerLogs()`). Only populated when `captureServerLogs` is `true` (the default).
+
+```ts twoslash
+import { expect, it, vi } from 'vitest'
+import { $fetch, clearServerLogs, getServerLogs } from '@nuxt/test-utils/e2e'
+
+it('captures console.log output from a server route', async () => {
+  clearServerLogs()
+  await $fetch('/api/log-test')
+  await vi.waitFor(() => {
+    expect(getServerLogs().some(line => line.includes('[test] server-log-marker'))).toBe(true)
+  })
+})
+```
+
+#### `clearServerLogs()`
+
+Clears the captured server log lines. Useful between requests when you want to assert only on the logs produced by a specific operation.
+
 ### Testing in a Browser
 
 We provide built-in support using Playwright within `@nuxt/test-utils`, either programmatically or via the Playwright test runner.

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

@@ -471,17 +471,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/
@@ -506,96 +496,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/accessibility.md

@@ -0,0 +1,155 @@
+---
+navigation.title: 'Accessibility'
+title: Nuxt accessibility
+description: Best practices for accessibility in Nuxt apps.
+---
+
+Most of what makes an app accessible is not specific to Nuxt: color contrast, form semantics, and ARIA work the same here as in any Vue or plain HTML application, and the [resources](#useful-resources) at the end of this guide cover them well.
+
+What Nuxt does change is navigation. Once your app has hydrated, it routes on the client, so the document is never reloaded and the browser no longer announces a new page or resets focus for you. Nuxt ships with features that fill some of that gap, and a few conventions cover the rest. This guide outlines best practices for handling that.
+
+::tip
+[`@nuxt/a11y`](https://github.com/nuxt/a11y) surfaces accessibility problems in your components while you develop, alongside the practices below. It is in alpha, so expect its API to change.
+::
+
+## Route Announcements
+
+Screen readers announce a full page load by themselves, but they have no way of knowing that a client-side navigation happened. [`<NuxtRouteAnnouncer>`](/docs/4.x/api/components/nuxt-route-announcer) solves this by rendering a hidden live region and writing the new page title into it after every navigation:
+
+```vue [app.vue]
+<template>
+  <NuxtRouteAnnouncer />
+  <NuxtPage />
+</template>
+```
+
+The announcer reads the title that Unhead rendered, so it is only as useful as your titles are. If two routes share the same `<title>`, users hear nothing on the way between them.
+
+When you need to announce something else, or to change how urgently it is announced, use [`useRouteAnnouncer`](/docs/4.x/api/composables/use-route-announcer):
+
+```vue [app/pages/search.vue]
+<script setup lang="ts">
+const { set } = useRouteAnnouncer()
+const { data: results } = await useFetch('/api/search')
+
+watch(results, (results) => {
+  set(`${results?.length ?? 0} results found`)
+})
+</script>
+```
+
+:read-more{title="NuxtRouteAnnouncer" to="/docs/4.x/api/components/nuxt-route-announcer"}
+
+For in-page updates that are not navigations, such as form validation or toasts, use [`<NuxtAnnouncer>`](/docs/4.x/api/components/nuxt-announcer) with [`useAnnouncer`](/docs/4.x/api/composables/use-announcer) instead.
+
+## Page Titles
+
+Because the route announcer follows the document title, giving every route a distinct title is the single most valuable thing you can do. Set a global template in `app.vue` and let each page fill in its own part:
+
+```vue [app.vue]
+<script setup lang="ts">
+useHead({
+  titleTemplate: title => title ? `${title} - Nuxt` : 'Nuxt',
+})
+</script>
+```
+
+```vue [app/pages/about.vue]
+<script setup lang="ts">
+useHead({
+  title: 'About us',
+})
+</script>
+```
+
+If your titles come from route metadata rather than from the page itself, you can read [`definePageMeta`](/docs/4.x/directory-structure/app/pages#page-metadata) values from [`useRoute`](/docs/4.x/api/composables/use-route) in a layout.
+
+:read-more{title="SEO and Meta" to="/docs/4.x/getting-started/seo-meta#dynamic-title"}
+
+## Links
+
+Use [`<NuxtLink>`](/docs/4.x/api/components/nuxt-link) for in-app navigation. It renders a real `<a href="...">`, which means it is focusable, appears in the tab order, and works with middle-click and "open in new tab", all of which you would have to reimplement on a `<div>` with a `@click` handler calling `navigateTo`.
+
+```vue
+<template>
+  <NuxtLink to="/about">About page</NuxtLink>
+</template>
+```
+
+In a menu or a set of breadcrumbs, the link matching the current route already exposes `aria-current="page"`, so assistive technology can tell which item you are on. Where a different token describes the relationship better, such as a step in a multi-page form, set [`ariaCurrentValue`](/docs/4.x/api/components/nuxt-link#routerlink):
+
+```vue
+<template>
+  <NuxtLink
+    to="/checkout/payment"
+    aria-current-value="step"
+  >Payment</NuxtLink>
+</template>
+```
+
+Links to files in your `public/` directory, or to another app on the same origin, are not routes that Vue Router knows about. Mark them as [`external`](/docs/4.x/api/components/nuxt-link#handling-static-file-and-cross-app-links) so the browser performs a real navigation instead of failing to match a route.
+
+:read-more{title="NuxtLink" to="/docs/4.x/api/components/nuxt-link"}
+
+## Focus Management
+
+After a client-side navigation, focus stays where it was, which is usually the link the user just activated. Vue Router does not move it and neither does Nuxt, so a keyboard user can end up tabbing through the whole header again to reach the content that just changed.
+
+A skip link as the first tab stop of your app is the conventional fix, and it helps on the initial page load too:
+
+```vue [app.vue]
+<template>
+  <a
+    class="skip-link"
+    href="#main"
+  >Skip to main content</a>
+  <AppHeader />
+  <main
+    id="main"
+    tabindex="-1"
+  >
+    <NuxtPage />
+  </main>
+</template>
+
+<style>
+.skip-link {
+  position: absolute;
+  left: -9999px;
+}
+.skip-link:focus {
+  position: static;
+}
+</style>
+```
+
+`<main>` is not focusable on its own, so it needs `tabindex="-1"` to accept focus from the skip link or from a script. Use `-1` rather than a positive value, which would move the element in the tab order and surprise everyone else.
+
+If it suits your app, you can go further and move focus to the main region after every navigation from a plugin:
+
+```ts [app/plugins/focus-main.client.ts]
+export default defineNuxtPlugin(() => {
+  useRouter().afterEach((to, from) => {
+    if (to.path === from.path) {
+      return
+    }
+    nextTick(() => document.getElementById('main')?.focus())
+  })
+})
+```
+
+::tip
+Navigate around your app with the keyboard alone. Tabbing from the skip link into `<main>` after a couple of navigations will surface most focus problems quickly.
+::
+
+## Scroll Behavior
+
+Nuxt scrolls to the top on a new route, restores the previous position when the user goes back, and scrolls to hash targets. If you need something different, such as smooth scrolling or a different offset, configure [`scrollBehaviorType`](/docs/4.x/guide/recipes/custom-routing#scroll-behavior-for-hash-links) or write your own `scrollBehavior` in [`router.options.ts`](/docs/4.x/guide/recipes/custom-routing#router-options). Bear in mind that smooth scrolling should respect the user's `prefers-reduced-motion` setting.
+
+:read-more{title="Custom routing" to="/docs/4.x/guide/recipes/custom-routing"}
+
+## Useful Resources
+
+- [Web Accessibility Initiative (WAI)](https://www.w3.org/WAI/)
+- [MDN: Accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility)
+- [Understanding WCAG 2.1](https://www.w3.org/WAI/WCAG21/Understanding/)

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/3.ai/1.mcp.md

@@ -26,7 +26,7 @@ The Nuxt MCP server provides the following tools organized by category:
 
 ### Documentation
 
-- **`list_documentation_pages`**: Lists all available Nuxt documentation pages with their categories and basic information. Supports version filtering (3.x, 4.x, or all)
+- **`list_documentation_pages`**: Lists all available Nuxt documentation pages with their categories and basic information. Supports version filtering (3.x, 4.x, 5.x, or all)
 - **`get_documentation_page`**: Retrieves documentation page content and details by path
 - **`get_getting_started_guide`**: Gets the getting started guide for a specific Nuxt version
 
@@ -40,6 +40,15 @@ The Nuxt MCP server provides the following tools organized by category:
 - **`list_deploy_providers`**: Lists all deployment providers and hosting platforms for Nuxt applications
 - **`get_deploy_provider`**: Retrieves deployment provider details and instructions by path
 
+### Modules
+
+- **`list_modules`**: Lists all available Nuxt modules with optional filtering and sorting by downloads, stars, or date
+- **`get_module`**: Retrieves complete details about a specific module including README, compatibility, maintainers, and stats
+
+### Changelog
+
+- **`get_changelog`**: Retrieves the latest releases from Nuxt core and official modules
+
 ## Prompts
 
 The Nuxt MCP server provides guided prompts for common workflows:
@@ -85,7 +94,7 @@ The Nuxt connector will appear in the composer's "Developer mode" tool later dur
 Add the server using the CLI command:
 
 ```bash
-claude mcp add --transport http nuxt-remote https://nuxt.com/mcp
+claude mcp add --transport http nuxt https://nuxt.com/mcp
 ```
 
 ### Claude Desktop
@@ -141,13 +150,30 @@ Or manually create/update `.cursor/mcp.json` in your project root:
 }
 ```
 
+### Gemini CLI
+
+1. Locate your Gemini CLI configuration file (usually `~/.gemini/settings.json` or as specified in your environment).
+2. Add the following configuration to your `mcpServers` object:
+
+```json [~/.gemini/settings.json]
+{
+  "mcpServers": {
+    "nuxt": {
+      "httpUrl": "https://nuxt.com/mcp"
+    }
+  }
+}
+```
+
+1. Restart your terminal session or reload the CLI. The Nuxt MCP server tools will now be available for use.
+
 ### Le Chat Mistral
 
 1. Navigate to "Intelligence" > "Connectors"
 2. Click on "Add Connector" button, then select "Custom MCP Connector"
 3. Create your Custom MCP Connector:
-    - Connector Name : `Nuxt`
-    - Connector Server : `https://nuxt.com/mcp`
+    - Connector Name: `Nuxt`
+    - Server URL: `https://nuxt.com/mcp`
 
 ### Visual Studio Code
 
@@ -207,6 +233,55 @@ To verify the MCP server is configured correctly:
 
 For more information on using MCP with GitHub Copilot coding agent, see [Extend coding agent with MCP](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp).
 
+### GitHub Copilot CLI
+
+1. Start GitHub Copilot CLI in interactive mode.
+2. Run `/mcp add`.
+3. Fill in the configuration form with:
+   - **Server Name**: `nuxt`
+   - **Server Type**: `HTTP`
+   - **URL**: `https://nuxt.com/mcp`
+   - **HTTP Headers**: leave empty
+   - **Tools**: `*`
+4. Press <kbd>Ctrl</kbd>+<kbd>S</kbd> to save. The MCP server is available immediately without restarting the CLI.
+
+Or add the server directly to `~/.copilot/mcp-config.json`:
+
+```json [~/.copilot/mcp-config.json]
+{
+  "mcpServers": {
+    "nuxt": {
+      "type": "http",
+      "url": "https://nuxt.com/mcp",
+      "tools": ["*"]
+    }
+  }
+}
+```
+
+Use `/mcp show` to confirm the server is configured and available.
+
+For more details, see [Adding MCP servers for GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers).
+
+### Google Antigravity
+
+1. Open the MCP store via the "..." dropdown at the top of the editor's agent panel.
+2. Click on "Manage MCP Servers"
+3. Click on "View raw config"
+4. Modify the `mcp_config.json` with your custom MCP server configuration:
+
+```json [mcp_config.json]
+{
+  "mcpServers": {
+    "nuxt": {
+      "serverUrl": "https://nuxt.com/mcp"
+    }
+  }
+}
+```
+
+1. Return to the "Manage MCP Servers" tab and click "Refresh". The Nuxt MCP server should now appear.
+
 ### Windsurf
 
 1. Open Windsurf and navigate to "Settings" > "Windsurf Settings" > "Cascade"
@@ -217,8 +292,7 @@ For more information on using MCP with GitHub Copilot coding agent, see [Extend
 {
   "mcpServers": {
     "nuxt": {
-      "type": "http",
-      "url": "https://nuxt.com/mcp"
+      "serverUrl": "https://nuxt.com/mcp"
     }
   }
 }
@@ -234,10 +308,7 @@ For more information on using MCP with GitHub Copilot coding agent, see [Extend
 {
   "context_servers": {
     "nuxt": {
-      "source": "custom",
-      "command": "npx",
-      "args": ["mcp-remote", "https://nuxt.com/mcp"],
-      "env": {}
+      "url": "https://nuxt.com/mcp"
     }
   }
 }

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

@@ -364,10 +364,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"}

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/12.nuxt-route-announcer.md

@@ -13,6 +13,8 @@ links:
 This component is available in Nuxt v3.12+.
 ::
 
+:read-more{title="Nuxt accessibility" to="/docs/4.x/guide/best-practices/accessibility#route-announcements"}
+
 ## Usage
 
 Add `<NuxtRouteAnnouncer/>` in your [`app.vue`](/docs/4.x/directory-structure/app/app) or [`app/layouts/`](/docs/4.x/directory-structure/app/layouts) to enhance accessibility by informing assistive technologies about page title changes. This ensures that navigational changes are announced to users relying on screen readers.

package/4.api/1.components/4.nuxt-link.md

@@ -12,6 +12,8 @@ links:
 `<NuxtLink>` is a drop-in replacement for both Vue Router's `<RouterLink>` component and HTML's `<a>` tag. It intelligently determines whether the link is _internal_ or _external_ and renders it accordingly with available optimizations (prefetching, default attributes, etc.)
 ::
 
+:read-more{title="Nuxt accessibility" to="/docs/4.x/guide/best-practices/accessibility#links"}
+
 ## Internal Routing
 
 In this example, we use `<NuxtLink>` component to link to another page of the application.

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-route-announcer.md

@@ -18,6 +18,8 @@ This composable is available in Nuxt v3.12+.
 A composable which observes the page title changes and updates the announcer message accordingly. Used by [`<NuxtRouteAnnouncer>`](/docs/4.x/api/components/nuxt-route-announcer) and controllable.
 It hooks into Unhead's `dom:rendered` hook to read the page's title and set it as the announcer message.
 
+:read-more{title="Nuxt accessibility" to="/docs/4.x/guide/best-practices/accessibility#route-announcements"}
+
 ## Parameters
 
 - `politeness`: Sets the urgency for screen reader announcements: `off` (disable the announcement), `polite` (waits for silence), or `assertive` (interrupts immediately).  (default `polite`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "4.5.2-29756973.d1e6ba2e",
+  "version": "4.5.2-29757143.58d8fcc3",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",