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

package/3.guide/1.concepts/4.server-engine.md

@@ -16,7 +16,7 @@ It is shipped with many features:
 
 ## API Layer
 
-Server [API endpoints](/docs/4.x/directory-structure/server#server-routes) and [Middleware](/docs/4.x/directory-structure/server#server-middleware) are added by Nitro that internally uses [h3](https://github.com/h3js/h3).
+Server [API endpoints](/docs/directory-structure/server#server-routes) and [Middleware](/docs/directory-structure/server#server-middleware) are added by Nitro that internally uses [h3](https://github.com/h3js/h3).
 
 Key features include:
 
@@ -26,15 +26,15 @@ Key features include:
 
 Check out [the h3 docs](https://github.com/h3js/h3) for more information.
 
-::read-more{to="/docs/4.x/directory-structure/server#server-routes"}
+::read-more{to="/docs/directory-structure/server#server-routes"}
 Learn more about the API layer in the `server/` directory.
 ::
 
 ## Direct API Calls
 
-Nitro allows 'direct' calling of routes via the globally-available [`$fetch`](/docs/4.x/api/utils/dollarfetch) helper. This will make an API call to the server if run on the browser, but will directly call the relevant function if run on the server, **saving an additional API call**.
+Nitro allows 'direct' calling of routes via the globally-available [`$fetch`](/docs/api/utils/dollarfetch) helper. This will make an API call to the server if run on the browser, but will directly call the relevant function if run on the server, **saving an additional API call**.
 
-[`$fetch`](/docs/4.x/api/utils/dollarfetch) API is using [ofetch](https://github.com/unjs/ofetch), with key features including:
+[`$fetch`](/docs/api/utils/dollarfetch) API is using [ofetch](https://github.com/unjs/ofetch), with key features including:
 
 - Automatic parsing of JSON responses (with access to raw response if needed)
 - Request body and params are automatically handled, with correct `Content-Type` headers
@@ -45,7 +45,7 @@ For more information on `$fetch` features, check out [ofetch](https://github.com
 
 When using API routes (or middleware), Nitro will generate typings for these routes as long as you are returning a value instead of using `res.end()` to send a response.
 
-You can access these types when using [`$fetch()`](/docs/4.x/api/utils/dollarfetch) or [`useFetch()`](/docs/4.x/api/composables/use-fetch).
+You can access these types when using [`$fetch()`](/docs/api/utils/dollarfetch) or [`useFetch()`](/docs/api/composables/use-fetch).
 
 ## Standalone Server
 
@@ -53,7 +53,7 @@ Nitro produces a standalone server dist that is independent of `node_modules`.
 
 The server in Nuxt 2 is not standalone and requires part of Nuxt core to be involved by running `nuxt start` (with the [`nuxt-start`](https://www.npmjs.com/package/nuxt-start) or [`nuxt`](https://www.npmjs.com/package/nuxt) distributions) or custom programmatic usage, which is fragile and prone to breakage and not suitable for serverless and service worker environments.
 
-Nuxt generates this dist when running `nuxt build` into a [`.output`](/docs/4.x/directory-structure/output) directory.
+Nuxt generates this dist when running `nuxt build` into a [`.output`](/docs/directory-structure/output) directory.
 
 The output contains runtime code to run your Nuxt server in any environment (including experimental browser service workers!) and serve your static files, making it a true hybrid framework for the JAMstack. In addition, Nuxt implements a native storage layer, supporting multi-source drivers and local assets.
 

package/3.guide/1.concepts/5.modules.md

@@ -7,7 +7,7 @@ description: "Nuxt provides a module system to extend the framework core and sim
 
 When developing production-grade applications with Nuxt you might find that the framework's core functionality is not enough. Nuxt can be extended with configuration options and plugins, but maintaining these customizations across multiple projects can be tedious, repetitive and time-consuming. On the other hand, supporting every project's needs out of the box would make Nuxt very complex and hard to use.
 
-This is one of the reasons why Nuxt provides a module system that makes it possible to extend the core. Nuxt modules are async functions that sequentially run when starting Nuxt in development mode using [`nuxt dev`](/docs/4.x/api/commands/dev) or building a project for production with [`nuxt build`](/docs/4.x/api/commands/build). They can override templates, configure webpack loaders, add CSS libraries, and perform many other useful tasks.
+This is one of the reasons why Nuxt provides a module system that makes it possible to extend the core. Nuxt modules are async functions that sequentially run when starting Nuxt in development mode using [`nuxt dev`](/docs/api/commands/dev) or building a project for production with [`nuxt build`](/docs/api/commands/build). They can override templates, configure webpack loaders, add CSS libraries, and perform many other useful tasks.
 
 Best of all, Nuxt modules can be distributed in npm packages. This makes it possible for them to be reused across projects and shared with the community, helping create an ecosystem of high-quality add-ons.
 
@@ -17,7 +17,7 @@ Explore Nuxt Modules
 
 ## Add Nuxt Modules
 
-Once you have installed the modules you can add them to your [`nuxt.config.ts`](/docs/4.x/directory-structure/nuxt-config) file under the `modules` property. Module developers usually provide additional steps and details for usage.
+Once you have installed the modules you can add them to your [`nuxt.config.ts`](/docs/directory-structure/nuxt-config) file under the `modules` property. Module developers usually provide additional steps and details for usage.
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -52,10 +52,10 @@ export default defineNuxtConfig({
 })
 ```
 
-:read-more{to="/docs/4.x/guide/going-further/layers#disabling-modules-from-layers"}
+:read-more{to="/docs/guide/going-further/layers#disabling-modules-from-layers"}
 
 ## Create a Nuxt Module
 
 Everyone has the opportunity to develop modules and we cannot wait to see what you will build.
 
-:read-more{to="/docs/4.x/guide/modules" title="Module Author Guide"}
+:read-more{to="/docs/guide/modules" title="Module Author Guide"}

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

@@ -0,0 +1,198 @@
+---
+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/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/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/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/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/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/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/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.
+
+When a `<NuxtLink>` to a [server-only page](/docs/directory-structure/app/pages#server-only-pages) is prefetched, its island response is prefetched too, so the round trip happens before the user navigates rather than during the navigation. The prefetched response is cached against the island's name, props and context, which is the same key the island uses when it mounts. A failed prefetch is not fatal: the island is fetched again on mount.
+
+::note
+This applies to the island that renders a whole `.server.vue` page. Islands used within a page are still fetched when they mount.
+::
+
+## 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/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/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.
+- Using islands can significantly increase the number of chunks generated at build time ([#34855](https://github.com/nuxt/nuxt/issues/34855)).
+- With webpack and Rspack, scoped `:slotted()` styles in server component slots can fail because server and client builds may generate different scope IDs ([#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/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/directory-structure/app/components#server-components"}
+Read more about server component file conventions in the components directory documentation.
+::

package/3.guide/1.concepts/7.esm.md

@@ -116,7 +116,7 @@ const { named } = pkg;
 
 ## Troubleshooting ESM Issues
 
-If you encounter these errors, the issue is almost certainly with the upstream library. They need to [fix their library](/docs/4.x/guide/concepts/esm#library-author-guide) to support being imported by Node.
+If you encounter these errors, the issue is almost certainly with the upstream library. They need to [fix their library](/docs/guide/concepts/esm#library-author-guide) to support being imported by Node.
 
 ### Transpiling Libraries
 
@@ -197,7 +197,7 @@ import { default as pkg } from 'cjs-pkg'
 import('cjs-pkg').then(m => m.default || m).then(console.log)
 ```
 
-For handling more complex situations and more safety, we recommend and internally use [mlly](https://github.com/unjs/mlly) in Nuxt that can preserve named exports.
+For handling more complex situations and more safety, we recommend [mlly](https://github.com/unjs/mlly), which can preserve named exports.
 
 ```js
 import { interopDefault } from 'mlly'
@@ -280,16 +280,16 @@ const someFile = require.resolve('./lib/foo.js')
 ```
 
 ```js [After]
-import { resolvePath } from 'mlly'
+import { resolveModulePath } from 'exsolve'
 
-const someFile = await resolvePath('my-lib', { url: import.meta.url })
+const someFile = resolveModulePath('my-lib', { from: import.meta.url })
 ```
 
 ::
 
 ### Best Practices
 
-- Prefer named exports rather than default export. This helps reduce CJS conflicts. (see [Default exports](/docs/4.x/guide/concepts/esm#default-exports) section)
+- Prefer named exports rather than default export. This helps reduce CJS conflicts. (see [Default exports](/docs/guide/concepts/esm#default-exports) section)
 
 - Avoid depending on Node.js built-ins and CommonJS or Node.js-only dependencies as much as possible to make your library usable in Browsers and Edge Workers without needing Nitro polyfills.
 

package/3.guide/1.concepts/8.typescript.md

@@ -5,7 +5,7 @@ description: "Nuxt is fully typed and provides helpful shortcuts to ensure you h
 
 ## Type-checking
 
-By default, Nuxt doesn't check types when you run [`nuxt dev`](/docs/4.x/api/commands/dev) or [`nuxt build`](/docs/4.x/api/commands/build), for performance reasons.
+By default, Nuxt doesn't check types when you run [`nuxt dev`](/docs/api/commands/dev) or [`nuxt build`](/docs/api/commands/build), for performance reasons.
 
 To enable type-checking at build or development time, install `vue-tsc` and `typescript` as development dependency:
 
@@ -33,13 +33,13 @@ To enable type-checking at build or development time, install `vue-tsc` and `typ
 
 ::
 
-Then, run [`nuxt typecheck`](/docs/4.x/api/commands/typecheck) command to check your types:
+Then, run [`nuxt typecheck`](/docs/api/commands/typecheck) command to check your types:
 
 ```bash [Terminal]
 npx nuxt typecheck
 ```
 
-To enable type-checking at build or development time, you can also use the [`typescript.typeCheck`](/docs/4.x/api/nuxt-config#typecheck) option in your `nuxt.config` file:
+To enable type-checking at build or development time, you can also use the [`typescript.typeCheck`](/docs/api/nuxt-config#typecheck) option in your `nuxt.config` file:
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -51,12 +51,12 @@ export default defineNuxtConfig({
 
 ## Auto-generated Types
 
-Nuxt projects rely on auto-generated types to work properly. These types are stored in the [`.nuxt`](/docs/4.x/directory-structure/nuxt) directory and are generated when you run the dev server or build your application. You can also generate these files manually by running `nuxt prepare`.
+Nuxt projects rely on auto-generated types to work properly. These types are stored in the [`.nuxt`](/docs/directory-structure/nuxt) directory and are generated when you run the dev server or build your application. You can also generate these files manually by running `nuxt prepare`.
 
-The generated `tsconfig.json` files inside the [`.nuxt`](/docs/4.x/directory-structure/nuxt) directory include **recommended basic TypeScript configuration** for your project, references to [auto-imports](/docs/4.x/guide/concepts/auto-imports), [API route types](/docs/4.x/guide/concepts/server-engine#typed-api-routes), path aliases like `#imports`, `~/file`, or `#build/file`, and more.
+The generated `tsconfig.json` files inside the [`.nuxt`](/docs/directory-structure/nuxt) directory include **recommended basic TypeScript configuration** for your project, references to [auto-imports](/docs/guide/concepts/auto-imports), [API route types](/docs/guide/concepts/server-engine#typed-api-routes), path aliases like `#imports`, `~/file`, or `#build/file`, and more.
 
 ::warning
-Nuxt relies on this configuration, and [Nuxt modules](/docs/4.x/guide/modules) can extend it as well. For this reason, it is not recommended to modify your `tsconfig.json` file directly, as doing so could overwrite important settings. Instead, extend it via `nuxt.config.ts`. [Learn more about extending the configuration here](/docs/4.x/directory-structure/tsconfig).
+Nuxt relies on this configuration, and [Nuxt modules](/docs/guide/modules) can extend it as well. For this reason, it is not recommended to modify your `tsconfig.json` file directly, as doing so could overwrite important settings. Instead, extend it via `nuxt.config.ts`. [Learn more about extending the configuration here](/docs/directory-structure/tsconfig).
 ::
 
 ::tip{icon="i-lucide-video" to="https://youtu.be/umLI7SlPygY" target="_blank"}
@@ -79,7 +79,7 @@ When you run `nuxt dev`, `nuxt build` or `nuxt prepare`, Nuxt will generate mult
 Each of these files is configured to reference the appropriate dependencies and provide optimal type-checking for their specific context.
 
 ::note
-For backward compatibility, Nuxt still generates `.nuxt/tsconfig.json`. However, we recommend using [TypeScript project references](/docs/4.x/directory-structure/tsconfig) with the new configuration files (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, etc.) for better type safety and performance. This legacy file will be removed in a future version of Nuxt.
+For backward compatibility, Nuxt still generates `.nuxt/tsconfig.json`. However, we recommend using [TypeScript project references](/docs/directory-structure/tsconfig) with the new configuration files (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, etc.) for better type safety and performance. This legacy file will be removed in a future version of Nuxt.
 ::
 
 ### Benefits of Project References
@@ -99,7 +99,7 @@ Similarly:
 - For the `server` context, place the augmentation file in the `server/` directory.
 - For types that are **shared between the app and server**, place the file in the `shared/` directory.
 
-::read-more{to="/docs/4.x/guide/modules/recipes-advanced#extend-typescript-config"}
+::read-more{to="/docs/guide/modules/recipes-advanced#extend-typescript-config"}
 Read more about augmenting specific type contexts from **files outside those contexts** in the Module Author Guide.
 ::
 
@@ -107,7 +107,7 @@ Read more about augmenting specific type contexts from **files outside those con
 
 TypeScript comes with certain checks to give you more safety and analysis of your program.
 
-[Strict checks](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html#getting-stricter-checks) are enabled by default in Nuxt when the [`typescript.typeCheck`](/docs/4.x/guide/concepts/typescript#type-checking) option is enabled to give you greater type safety.
+[Strict checks](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html#getting-stricter-checks) are enabled by default in Nuxt when the [`typescript.typeCheck`](/docs/guide/concepts/typescript#type-checking) option is enabled to give you greater type safety.
 
 If you are currently converting your codebase to TypeScript, you may want to temporarily disable strict checks by setting `strict` to `false` in your `nuxt.config`:
 

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/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/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/api/components/nuxt-route-announcer"}
+
+For in-page updates that are not navigations, such as form validation or toasts, use [`<NuxtAnnouncer>`](/docs/api/components/nuxt-announcer) with [`useAnnouncer`](/docs/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/directory-structure/app/pages#page-metadata) values from [`useRoute`](/docs/api/composables/use-route) in a layout.
+
+:read-more{title="SEO and Meta" to="/docs/getting-started/seo-meta#dynamic-title"}
+
+## Links
+
+Use [`<NuxtLink>`](/docs/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/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/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/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/guide/recipes/custom-routing#scroll-behavior-for-hash-links) or write your own `scrollBehavior` in [`router.options.ts`](/docs/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/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/hydration.md

@@ -47,7 +47,7 @@ const userTheme = localStorage.getItem('theme') || 'light'
 </script>
 ```
 
-**Solution**: You can use [`useCookie`](/docs/4.x/api/composables/use-cookie):
+**Solution**: You can use [`useCookie`](/docs/api/composables/use-cookie):
 
 ```html
 <template>
@@ -144,12 +144,12 @@ const greeting = hour < 12 ? 'Good morning' : 'Good afternoon'
 </script>
 ```
 
-**Solution**: Use [`NuxtTime`](/docs/4.x/api/components/nuxt-time) component or handle it client-side:
+**Solution**: Use [`NuxtTime`](/docs/api/components/nuxt-time) component or handle it client-side:
 
 ```html
 <template>
   <div>
-    <NuxtTime :date="new Date()" format="HH:mm" />
+    <NuxtTime :datetime="new Date()" format="HH:mm" />
   </div>
 </template>
 ```
@@ -178,8 +178,8 @@ onMounted(() => {
 
 ## In Summary
 
-1. **Use SSR-friendly composables**: [`useFetch`](/docs/4.x/api/composables/use-fetch), [`useAsyncData`](/docs/4.x/api/composables/use-async-data), [`useState`](/docs/4.x/api/composables/use-state)
-2. **Wrap client-only code**: Use [`ClientOnly`](/docs/4.x/api/components/client-only) component for browser-specific content
+1. **Use SSR-friendly composables**: [`useFetch`](/docs/api/composables/use-fetch), [`useAsyncData`](/docs/api/composables/use-async-data), [`useState`](/docs/api/composables/use-state)
+2. **Wrap client-only code**: Use [`ClientOnly`](/docs/api/components/client-only) component for browser-specific content
 3. **Consistent data sources**: Ensure server and client uses the same data
 4. **Avoid side effects in setup**: Move browser-dependent code to `onMounted`