@nuxt/docs-nightly 5.0.0-29741076.61a2183b → 5.0.0-29741325.e71f6f2a

package/1.getting-started/07.routing.md

@@ -6,6 +6,28 @@ navigation.icon: i-lucide-milestone
 
 One core feature of Nuxt is the file system router. Every Vue file inside the [`app/pages/`](/docs/4.x/directory-structure/app/pages) directory creates a corresponding URL (or route) that displays the contents of the file. By using dynamic imports for each page, Nuxt leverages code-splitting to ship the minimum amount of JavaScript for the requested route.
 
+::note
+Code-splitting is enabled by default and is recommended for most apps. If you have a specific reason to ship a single bundle instead, you can disable it in your [`nuxt.config`](/docs/4.x/api/nuxt-config):
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  vite: {
+    $client: {
+      build: {
+        rolldownOptions: {
+          output: {
+            codeSplitting: false,
+          },
+        },
+      },
+    },
+  },
+})
+```
+
+This ships all JavaScript in a single file. It is rarely beneficial — it usually increases the initial download, even on slow connections — so only disable code-splitting if you have measured that it helps your case.
+::
+
 ## Pages
 
 Nuxt routing is based on [vue-router](https://router.vuejs.org) and generates the routes from every component created in the [`app/pages/` directory](/docs/4.x/directory-structure/app/pages), based on their filename.

package/1.getting-started/08.seo-meta.md

@@ -33,9 +33,24 @@ export default defineNuxtConfig({
 })
 ```
 
+::note
+When you set [`app.cdnURL`](/docs/4.x/api/nuxt-config#cdnurl), assets in your [`public/`](/docs/4.x/directory-structure/public) directory (including `favicon.ico`) are served from that CDN. Nuxt resolves public assets against `cdnURL`, falling back to `app.baseURL`. However, a static `app.head` link such as `href: '/favicon.ico'` above is a literal path and is **not** resolved against `cdnURL`. To point the favicon at the resolved location, build the `href` from runtime config with [`useHead()`](/docs/4.x/api/composables/use-head) in `app.vue`:
+
+```vue [app/app.vue]
+<script setup lang="ts">
+const { cdnURL, baseURL } = useRuntimeConfig().app
+useHead({
+  link: [
+    { rel: 'icon', type: 'image/x-icon', href: `${cdnURL || baseURL}favicon.ico` },
+  ],
+})
+</script>
+```
+::
+
 You can also provide any of the keys listed below in [Types](/docs/4.x/getting-started/seo-meta#types).
 
-### Defaults Tags
+### Default Tags
 
 Some tags are provided by Nuxt by default to ensure your website works well out of the box.
 
@@ -142,7 +157,7 @@ If you need to duplicate tags across client-server boundaries, apply a `key` att
 
 Below are the non-reactive types used for [`useHead`](/docs/4.x/api/composables/use-head), [`app.head`](/docs/4.x/api/nuxt-config#head) and components.
 
-```ts
+```ts [Types]
 interface MetaObject {
   title?: string
   titleTemplate?: string | ((title?: string) => string)
@@ -231,7 +246,7 @@ If you want to use a function (for full control), then this cannot be set in you
 
 Now, if you set the title to `My Page` with [`useHead`](/docs/4.x/api/composables/use-head) on another page of your site, the title would appear as 'My Page - Site Title' in the browser tab. You could also pass `null` to default to 'Site Title'.
 
-### Template Params
+### Template Parameters
 
 You can use `templateParams` to provide additional placeholders in your `titleTemplate` besides the default `%s`. This allows for more dynamic title generation.
 
@@ -273,7 +288,7 @@ useHead({
 </script>
 ```
 
-## Examples
+## Example
 
 ### With `definePageMeta`
 

package/1.getting-started/09.transitions.md

@@ -418,7 +418,7 @@ When `<NuxtPage />` is used in `app.vue`, transitions can be configured with the
 Remember, this page transition cannot be overridden with `definePageMeta` on individual pages.
 ::
 
-## View Transitions API (experimental)
+## View Transitions API (Experimental)
 
 Nuxt ships with an experimental implementation of the [**View Transitions API**](https://developer.chrome.com/docs/web-platform/view-transitions) (see [MDN](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API)). This is an exciting new way to implement native browser transitions which (among other things) have the ability to transition between unrelated elements on different pages.
 

package/1.getting-started/10.data-fetching.md

@@ -14,7 +14,7 @@ In a nutshell:
 
 Both `useFetch` and `useAsyncData` share a common set of options and patterns that we will detail in the last sections.
 
-## The need for `useFetch` and `useAsyncData`
+## The Need for `useFetch` and `useAsyncData`
 
 Nuxt is a framework which can run isomorphic (or universal) code in both server and client environments. If the [`$fetch` function](/docs/4.x/api/utils/dollarfetch) is used to perform data fetching in the setup function of a Vue component, this may cause data to be fetched twice, once on the server (to render the HTML) and once again on the client (when the HTML is hydrated). This can cause hydration issues, increase the time to interactivity and cause unpredictable behavior.
 
@@ -546,8 +546,6 @@ const id = ref(null)
 const { data, status } = useLazyFetch(() => `/api/users/${id.value}`, {
   immediate: false,
 })
-
-const pending = computed(() => status.value === 'pending')
 </script>
 
 <template>
@@ -556,14 +554,14 @@ const pending = computed(() => status.value === 'pending')
     <input
       v-model="id"
       type="number"
-      :disabled="pending"
+      :disabled="status === 'pending'"
     >
 
     <div v-if="status === 'idle'">
       Type a user ID
     </div>
 
-    <div v-else-if="pending">
+    <div v-else-if="status === 'pending'">
       Loading ...
     </div>
 

package/1.getting-started/11.state-management.md

@@ -29,7 +29,7 @@ For example, doing `export myState = ref({})` would result in state shared acros
 Instead use `const useX = () => useState('x')`
 ::
 
-## Examples
+## Example
 
 ### Basic Usage
 
@@ -219,7 +219,7 @@ const color = useColor() // Same as useState('color')
 
 :video-accordion{title="Watch a video from Daniel Roe on how to deal with global state and SSR in Nuxt" videoId="dZSNW07sO-A"}
 
-## Using third-party libraries
+## Using Third-Party Libraries
 
 Nuxt **used to rely** on the Vuex library to provide global state management. If you are migrating from Nuxt 2, please head to [the migration guide](/docs/4.x/migration/configuration#vuex).
 

package/1.getting-started/14.layers.md

@@ -132,7 +132,7 @@ This pattern is useful for creating base layers with defaults that can be progre
 - **`~~/layers` directory** - Use for local layers that are part of your project
 - **`extends`** - Use for external dependencies (npm packages, remote repositories) or layers outside your project directory
 
-### Full Example with extends
+### Full Example with `extends`
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -163,7 +163,7 @@ Read more about layers in the **Layer Author Guide**.
 
 :video-accordion{title="Watch a video from Alexander Lichter about Nuxt Layers" videoId="fr5yo3aVkfA"}
 
-## Examples
+## Example
 
 ::card-group
   ::card{icon="i-simple-icons-github" title="Content Wind" to="https://github.com/Atinux/content-wind" target="_blank"}

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

@@ -543,6 +543,10 @@ You can partially hydrate a component by setting a `nuxt-client` attribute on th
 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.)

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

@@ -56,7 +56,7 @@ Be aware that you have to run [`nuxt prepare`](/docs/4.x/api/commands/prepare),
 If you create a composable without having the dev server running, TypeScript will throw an error, such as `Cannot find name 'useBar'.`
 ::
 
-## Examples
+## Example
 
 ### Nested Composables
 
@@ -69,7 +69,7 @@ export const useFoo = () => {
 }
 ```
 
-### Access plugin injections
+### Access Plugin Injections
 
 You can access [plugin injections](/docs/4.x/directory-structure/app/plugins#providing-helpers) from composables:
 

package/2.directory-structure/1.server.md

@@ -7,7 +7,7 @@ navigation.icon: i-vscode-icons-folder-type-server
 
 Nuxt automatically scans files inside these directories to register API and server handlers with Hot Module Replacement (HMR) support.
 
-```bash [Directory structure]
+```bash [Directory Structure]
 -| server/
 ---| api/
 -----| hello.ts      # /api/hello
@@ -21,6 +21,12 @@ Each file should export a default function defined with `defineEventHandler()` o
 
 The handler can directly return JSON data, a `Promise`, or a `Response` object.
 
+::important
+Do not import Vue app code (components, composables, or other app-only utilities) in your server routes or utilities, and do not import server-only code in your app.
+::
+
+:read-more{to="/docs/4.x/directory-structure/shared#why-you-cannot-mix-vue-and-nitro-code" title="Why You Cannot Mix Vue and Nitro Code"}
+
 ```ts twoslash [server/api/hello.ts]
 import { defineEventHandler } from 'nitro/h3'
 

package/2.directory-structure/1.shared.md

@@ -15,6 +15,22 @@ The `shared/` directory is available in Nuxt v3.14+.
 Code in the `shared/` directory cannot import any Vue or Nitro code.
 ::
 
+## Why You Cannot Mix Vue and Nitro Code
+
+Nuxt builds two separate bundles: the Vue app (client and server-side rendering) and the Nitro server (API routes, server middleware, server plugins). They are bundled independently and run in different contexts. Code in the `shared/` directory is used in both bundles, so it cannot import from either.
+
+### Vue App Code in Nitro
+
+Components and composables need the Vue app runtime and often the Nuxt context (for example `useNuxtApp()` or `useRoute()`), neither of which exists in Nitro. Importing them into server code can cause build or runtime errors, and can pull the Vue app's dependencies into your server bundle.
+
+### Nitro Code in the Vue App
+
+Server-only code (such as Node APIs, Nitro utilities, or server route handlers) must not run in the browser. Importing it into your app can break the client build, cause runtime errors in the browser, or leak server logic into the client bundle.
+
+### Type-Only Imports
+
+`import type` is erased at compile time and does not pull runtime code into the other bundle, so importing only types across the boundary may appear to work. Even so, keep shared types (such as API response types) in `shared/types/`, where they are auto-imported in both contexts. This keeps the boundary clear, avoids accidentally turning a type import into a value import later, and matches Nuxt's separate [type contexts](/docs/4.x/guide/concepts/typescript#project-references) for app, server, and shared code.
+
 :video-accordion{title="Watch a video from Vue School on sharing utils and types between app and server" videoId="nnAR-MO3q5M"}
 
 ## Usage
@@ -82,7 +98,7 @@ The way `shared/utils` and `shared/types` auto-imports work and are scanned is i
 
 Any other files you create in the `shared/` folder must be manually imported using the `#shared` alias (automatically configured by Nuxt):
 
-```ts
+```ts [Importing From #shared]
 // For files directly in the shared directory
 import capitalize from '#shared/capitalize'
 

package/3.guide/1.concepts/2.nuxt-lifecycle.md

@@ -5,7 +5,7 @@ description: "Understanding the lifecycle of Nuxt applications can help you gain
 
 The goal of this chapter is to provide a high-level overview of the different parts of the framework, their execution order, and how they work together.
 
-## Server lifecycle
+## Server Lifecycle
 
 On the server, the following steps are executed for every initial request to your application:
 
@@ -109,7 +109,7 @@ Before finalizing and sending the HTML, Nitro will call the [`render:html`](/doc
 
 ::
 
-## Client lifecycle
+## Client Lifecycle
 
 This part of the lifecycle is fully executed in the browser, no matter which Nuxt mode you've chosen.
 

package/3.guide/1.concepts/3.auto-imports.md

@@ -179,7 +179,7 @@ export default defineNuxtConfig({
 })
 ```
 
-## Auto-import from Third-Party Packages
+## Auto-Import from Third-Party Packages
 
 Nuxt also allows auto-importing from third-party packages.
 

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

@@ -6,7 +6,7 @@ description: Why fixing hydration issues is important
 
 When developing, you may face hydration issues. Don't ignore those warnings.
 
-## Why is it important to fix them?
+## Why Is It Important to Fix Them?
 
 Hydration mismatches are not just warnings - they are indicators of serious problems that can break your application:
 
@@ -21,7 +21,7 @@ Hydration mismatches are not just warnings - they are indicators of serious prob
 - **State inconsistencies**: Application state can become out of sync between what the user sees and what the application thinks is rendered
 - **SEO problems**: Search engines may index different content than what users actually see
 
-## How to detect them
+## How to Detect Them
 
 ### Development Console Warnings
 
@@ -29,7 +29,7 @@ Vue will log hydration mismatch warnings in the browser console during developme
 
 ![Screenshot of Vue hydration mismatch warning in the browser console](/assets/docs/best-practices/vue-console-hydration.png)
 
-## Common reasons
+## Common Reasons
 
 ### Browser-only APIs in Server Context
 
@@ -176,7 +176,7 @@ onMounted(() => {
 </script>
 ```
 
-## In summary
+## 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

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

@@ -264,7 +264,7 @@ It provides both lab and field data about a page. Lab data is useful for debuggi
 
 Each test can be run from different locations around the world, on real browsers, over any number of customizable network conditions.
 
-## Common problems
+## Common Problems
 
 When building more complex Nuxt applications, you will probably encounter some of the problems listed below. Understanding these problems and fixing them will help you improve performance of your website.
 

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

@@ -6,15 +6,15 @@ description: Best practices when using Nuxt plugins.
 
 Plugins in Nuxt allow you to extend your application with additional functionality. However, improper use can lead to performance bottlenecks. This guide outlines best practices to optimize your Nuxt plugins.
 
-## Avoid costly plugin setup
+## Avoid Costly Plugin Setup
 
 A large number of plugins can cause performance issues, especially if they require expensive computations or take too long to initialize. Since plugins run during the hydration phase, inefficient setups can block rendering and degrade the user experience.
 
-## Use Composition whenever possible
+## Use Composition Whenever Possible
 
 Whenever possible, favor composition over plugins. Just like in Vue, many utilities and composables can be used directly without the need for a plugin. This keeps your project lightweight and improves maintainability.
 
-## If `async`, enable `parallel`
+## If `async`, Enable `parallel`
 
 By default, all plugins loads synchronously.
 When defining asynchronous plugins, setting `parallel: true` allows multiple plugins to load concurrently, improving performance by preventing blocking operations.

package/3.guide/3.ai/1.mcp.md

@@ -4,7 +4,7 @@ description: Use Nuxt documentation in your AI assistants with Model Context Pro
 navigation.title: MCP Server
 ---
 
-## What is MCP?
+## What Is MCP?
 
 MCP (Model Context Protocol) is a standardized protocol that enables AI assistants to access external data sources and tools. Nuxt provides an MCP server that allows AI assistants like Claude Code, Cursor, and Windsurf to access documentation, blog posts, and deployment guides directly.
 

package/3.guide/3.ai/2.llms-txt.md

@@ -4,13 +4,13 @@ description: How to get AI tools like Cursor, Windsurf, GitHub Copilot, ChatGPT,
 navigation.title: LLMs.txt
 ---
 
-## What is LLMs.txt?
+## What Is LLMs.txt?
 
 LLMs.txt is a structured documentation format specifically designed for large language models (LLMs). Nuxt provides LLMs.txt files that contain comprehensive information about the framework, making it easy for AI tools to understand and assist with Nuxt development.
 
 These files are optimized for AI consumption and contain structured information about concepts, APIs, usage patterns, and best practices.
 
-## Available routes
+## Available Routes
 
 We provide LLMs.txt routes to help AI tools access our documentation:
 
@@ -25,7 +25,7 @@ We provide LLMs.txt routes to help AI tools access our documentation:
 Use `/llms-full.txt` only if you need comprehensive implementation details and your AI tool supports large contexts (200K+ tokens).
 ::
 
-## Important usage notes
+## Important Usage Notes
 
 ::warning{icon="i-lucide-alert-triangle"}
 **@-symbol must be typed manually** - When using tools like Cursor or Windsurf, the `@` symbol must be typed by hand in the chat interface. Copy-pasting breaks the tool's ability to recognize it as a context reference.

package/3.guide/4.modules/8.ecosystem.md

@@ -23,7 +23,7 @@ Watch Vue School video about Nuxt module types.
 
 Any community modules are welcome to be listed on [the module list](/modules). To be listed, [open an issue in the nuxt/modules](https://github.com/nuxt/modules/issues/new?template=module_request.yml) repository. The Nuxt team can help you to apply best practices before listing.
 
-## Join nuxt-modules
+## Join `nuxt-modules`
 
 By moving your modules to [nuxt-modules](https://github.com/nuxt-modules), there is always someone else to help, and this way, we can join forces to make one perfect solution.
 

package/3.guide/5.recipes/1.custom-routing.md

@@ -3,7 +3,7 @@ title: "Custom Routing"
 description: "In Nuxt, your routing is defined by the structure of your files inside the pages directory. However, since it uses vue-router under the hood, Nuxt offers you several ways to add custom routes in your project."
 ---
 
-## Adding custom routes
+## Adding Custom Routes
 
 In Nuxt, your routing is defined by the structure of your files inside the [app/pages directory](/docs/4.x/directory-structure/app/pages). However, since it uses [vue-router](https://router.vuejs.org) under the hood, Nuxt offers you several ways to add custom routes in your project.
 

package/3.guide/5.recipes/4.sessions-and-authentication.md

@@ -9,7 +9,7 @@ In this recipe we'll be setting up authentication in a full-stack Nuxt app using
 
 The module uses secured & sealed cookies to store session data, so you don't need to setup a database to store session data.
 
-## Install nuxt-auth-utils
+## Install `nuxt-auth-utils`
 
 Install the `nuxt-auth-utils` module using the `nuxt` CLI.
 

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

@@ -334,6 +334,10 @@ export default defineNuxtConfig({
 
 :read-more{to="/docs/4.x/directory-structure/app/components#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).
+::
+
 ::read-more{icon="i-simple-icons-github" to="https://github.com/nuxt/nuxt/issues/19772" target="_blank"}
 You can follow the server components roadmap on GitHub.
 ::
@@ -911,9 +915,11 @@ export default defineNuxtConfig({
 
 ## pendingWhenIdle
 
-For `useAsyncData` and `useFetch`, whether `pending` should be `true` when data has not yet started to be fetched.
+`pendingWhenIdle` controls the `pending` ref returned by `useAsyncData` and `useFetch`.
 
-This flag is disabled by default, but you can enable this feature:
+When `pendingWhenIdle` is `false` (the default), `pending` is `true` while a request is in flight and matches `status === 'pending'`. While `status` is `idle`, `pending` stays `false`. You can see this with `{ immediate: false }`, or with `{ server: false }` during server rendering.
+
+Set `pendingWhenIdle: true` so `pending` is also `true` when `status` is `idle` and no cached data is available. Use `status` when your loading UI needs to distinguish `idle` from an in-flight request.
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({

package/4.api/1.components/1.client-only.md

@@ -19,7 +19,7 @@ The content of the default slot will be tree-shaken out of the server build. (Th
 - `placeholderTag` | `fallbackTag`: specify a tag to be rendered server-side.
 - `placeholder` | `fallback`: specify a content to be rendered server-side.
 
-```vue
+```vue [app/pages/example.vue]
 <template>
   <div>
     <Sidebar />
@@ -55,7 +55,7 @@ The content of the default slot will be tree-shaken out of the server build. (Th
 </template>
 ```
 
-## Examples
+## Example
 
 ### Accessing HTML Elements
 

package/4.api/1.components/13.nuxt-time.md

@@ -18,7 +18,7 @@ The `<NuxtTime>` component lets you display dates and times in a locale-friendly
 
 You can use the `<NuxtTime>` component anywhere in your app:
 
-```vue
+```vue [app/app.vue]
 <template>
   <NuxtTime :datetime="Date.now()" />
 </template>
@@ -36,7 +36,7 @@ The date and time value to display. You can provide:
 - A timestamp (number)
 - An ISO-formatted date string
 
-```vue
+```vue [app/app.vue]
 <template>
   <NuxtTime :datetime="Date.now()" />
   <NuxtTime :datetime="new Date()" />
@@ -52,7 +52,7 @@ The date and time value to display. You can provide:
 
 The [BCP 47 language tag](https://datatracker.ietf.org/doc/html/rfc5646) for formatting (e.g., 'en-US', 'fr-FR', 'ja-JP'):
 
-```vue
+```vue [app/app.vue]
 <template>
   <NuxtTime
     :datetime="Date.now()"
@@ -65,7 +65,7 @@ The [BCP 47 language tag](https://datatracker.ietf.org/doc/html/rfc5646) for for
 
 The component accepts any property from the [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) options:
 
-```vue
+```vue [app/app.vue]
 <template>
   <NuxtTime
     :datetime="Date.now()"
@@ -88,7 +88,7 @@ This would output something like: "April 22, 2025, 08:30 AM"
 
 Enables relative time formatting using the Intl.RelativeTimeFormat API:
 
-```vue
+```vue [app/app.vue]
 <template>
   <!-- Shows something like "5 minutes ago" -->
   <NuxtTime
@@ -106,7 +106,7 @@ When `relative` is set to `true`, the component also accepts properties from [In
 Due to `style` being a reserved prop, `relativeStyle` prop is used instead.
 ::
 
-```vue
+```vue [app/app.vue]
 <template>
   <NuxtTime
     :datetime="Date.now() - 3 * 24 * 60 * 60 * 1000"
@@ -119,11 +119,11 @@ Due to `style` being a reserved prop, `relativeStyle` prop is used instead.
 
 This would output something like: "3 days ago" or "last Friday" depending on the `numeric` setting.
 
-## Examples
+## Example
 
 ### Basic Usage
 
-```vue
+```vue [app/app.vue]
 <template>
   <NuxtTime :datetime="Date.now()" />
 </template>
@@ -131,7 +131,7 @@ This would output something like: "3 days ago" or "last Friday" depending on the
 
 ### Custom Formatting
 
-```vue
+```vue [app/app.vue]
 <template>
   <NuxtTime
     :datetime="Date.now()"
@@ -149,7 +149,7 @@ This would output something like: "3 days ago" or "last Friday" depending on the
 
 ### Relative Time
 
-```vue
+```vue [app/app.vue]
 <template>
   <div>
     <p>
@@ -179,7 +179,7 @@ This would output something like: "3 days ago" or "last Friday" depending on the
 
 ### With Custom Locale
 
-```vue
+```vue [app/app.vue]
 <template>
   <div>
     <NuxtTime

package/4.api/1.components/6.nuxt-error-boundary.md

@@ -16,7 +16,7 @@ The `<NuxtErrorBoundary>` uses Vue's [`onErrorCaptured`](https://vuejs.org/api/c
 
 - `@error`: Event emitted when the default slot of the component throws an error.
 
-  ```vue
+  ```vue [app/app.vue]
   <template>
     <NuxtErrorBoundary @error="logSomeError">
       <!-- ... -->
@@ -28,7 +28,7 @@ The `<NuxtErrorBoundary>` uses Vue's [`onErrorCaptured`](https://vuejs.org/api/c
 
 - `#error`: Specify a fallback content to display in case of error.
 
-  ```vue
+  ```vue [app/app.vue]
   <template>
     <NuxtErrorBoundary>
       <!-- ... -->
@@ -45,13 +45,13 @@ The `<NuxtErrorBoundary>` uses Vue's [`onErrorCaptured`](https://vuejs.org/api/c
 
 :read-more{to="/docs/4.x/getting-started/error-handling"}
 
-## Examples
+## Example
 
-### Accessing `error` and `clearError` in script
+### Accessing `error` and `clearError` in Script
 
 You can access `error` and `clearError` properties within the component's script as below:
 
-```vue
+```vue [app/app.vue]
 <template>
   <NuxtErrorBoundary ref="errorBoundary">
     <!-- ... -->

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

@@ -56,6 +56,27 @@ Component props and context are sent as GET query parameters to enable caching.
 By default, component islands are scanned from the `~/components/islands/` directory. So the `~/components/islands/MyIsland.vue` component could be rendered with `<NuxtIsland name="MyIsland" />`.
 ::
 
+## Known Limitations
+
+### `useId` in island and server components
+
+Each island is rendered in its own Vue app on the server, so Vue's [`useId`](https://vuejs.org/api/composition-api-helpers#useid) counter restarts for every island. Ids generated inside an island can therefore collide with ids generated by other islands on the same page, or by the rest of your app.
+
+**Workaround**: set a distinct [`idPrefix`](https://vuejs.org/api/application#app-config-idprefix) on the island's Vue app from a server plugin, based on the island context id:
+
+```ts [plugins/island-id-prefix.server.ts]
+export default defineNuxtPlugin((nuxtApp) => {
+  const islandContext = nuxtApp.ssrContext?.islandContext
+  if (islandContext) {
+    nuxtApp.vueApp.config.idPrefix = `${islandContext.id}-v`
+  }
+})
+```
+
+- **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.
+
 ## Slots
 
 Slots can be passed to an island component if declared.

package/4.api/2.composables/on-prehydrate.md

@@ -20,7 +20,7 @@ This is an advanced utility and should be used with care. For example, [`nuxt-ti
 
 ## Usage
 
-Call `onPrehydrate` in the setup function of a Vue component (e.g., in `<script setup>`) or in a plugin. It only has an effect when called on the server and will not be included in your client build.
+Call `onPrehydrate` in the setup function of a Vue component (e.g., in `<script setup>`) or in a plugin. The call itself only has an effect when made on the server and is stripped from your client build. The callback you pass, however, is serialized and inlined into the HTML, so it runs in the **browser** immediately before Nuxt hydrates. This means it can access browser globals like `window` and the DOM.
 
 ## Type
 
@@ -47,8 +47,8 @@ export function onPrehydrate (callback: string | ((el: HTMLElement) => void), ke
 <script setup lang="ts">
 declare const window: Window
 // ---cut---
-// Run code before Nuxt hydrates
 onPrehydrate(() => {
+  // Runs in the browser, right before Nuxt hydrates
   console.log(window)
 })
 
@@ -68,3 +68,13 @@ const prehydrateId = onPrehydrate((el) => {})
   </div>
 </template>
 ```
+
+Under the hood, the callback is stringified and minified at build time, then inlined as a `<script>` tag in the server-rendered HTML, just before the closing `</body>` tag. For the example above, the rendered HTML includes something like:
+
+```html
+<div data-prehydrate-id=":b3qlvSiBeH:"> Hi there </div>
+<script>(()=>{console.log(window)})()</script>
+<script>document.querySelectorAll('[data-prehydrate-id*=":b3qlvSiBeH:"]').forEach(el=>{console.log(el.outerHTML)})</script>
+```
+
+When the callback accepts an `el` parameter, the component's root element is tagged with a `data-prehydrate-id` attribute so the inlined script can find it.