@nuxt/docs-nightly 4.4.3-29561554.e9b2fa64 → 4.4.3-29571486.e4b31efa

package/1.getting-started/18.upgrade.md

@@ -62,6 +62,7 @@ When you set your `future.compatibilityVersion` to `5`, defaults throughout your
 - **Normalized Page Names**: Page component names will [match their route names](/docs/4.x/getting-started/upgrade#normalized-page-component-names) for consistent `<KeepAlive>` behavior
 - **`clearNuxtState` resets to defaults**: `clearNuxtState` will [reset state to its initial value](/docs/4.x/getting-started/upgrade#respect-defaults-when-clearing-usestate) instead of setting it to `undefined`
 - **Non-async `callHook`**: [`callHook` may return `void`](/docs/4.x/getting-started/upgrade#non-async-callhook) instead of always returning a `Promise`
+- **Comment node placeholders**: Client-only components use [comment nodes instead of `<div>`](/docs/4.x/getting-started/upgrade#client-only-comment-placeholders) as SSR placeholders, fixing a scoped styles hydration issue
 - Other Nuxt 5 improvements and changes as they become available
 
 ::note
@@ -227,6 +228,46 @@ export default defineNuxtConfig({
 })
 ```
 
+### Client-Only Comment Placeholders
+
+🚦 **Impact Level**: Minimal
+
+#### What Changed
+
+With `compatibilityVersion: 5`, client-only components (`.client.vue` files and `createClientOnly()` wrappers) now render an HTML comment (`<!--placeholder-->`) on the server instead of an empty `<div>` element.
+
+#### Reasons for Change
+
+When the placeholder `<div>` and the actual component root share the same tag name, Vue's runtime skips re-applying `setScopeId` during hydration. This causes scoped styles to be missing after the component mounts. Using a comment node avoids the tag name collision entirely.
+
+#### Migration Steps
+
+If you rely on the placeholder `<div>` to inherit attributes (`class`, `style`, etc.) for layout purposes (e.g., reserving space to prevent layout shift), wrap the component in `<ClientOnly>` with a `#fallback` slot instead:
+
+```diff
+- <MyComponent class="placeholder" style="min-height: 200px" />
++ <ClientOnly>
++   <MyComponent />
++   <template #fallback>
++     <div class="placeholder" style="min-height: 200px"></div>
++   </template>
++ </ClientOnly>
+```
+
+::tip
+You can test this feature early by setting `future.compatibilityVersion: 5` (see [Testing Nuxt 5](/docs/4.x/getting-started/upgrade#testing-nuxt-5)) or by enabling it explicitly with `experimental.clientNodePlaceholder: true`.
+::
+
+Alternatively, you can revert to the previous `<div>` placeholder behavior with:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    clientNodePlaceholder: false,
+  },
+})
+```
+
 ## Migrating to Nuxt 4
 
 Nuxt 4 includes significant improvements and changes. This guide will help you migrate your existing Nuxt 3 application to Nuxt 4.

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

@@ -168,7 +168,7 @@ This is useful when you want to manage layouts centrally in your configuration r
 
 :link-example{to="/docs/4.x/examples/features/layouts"}
 
-## Passing Props to Layouts
+## Passing Props to Layouts :badge[+4.4]{color="primary" class="align-middle"}
 
 You can pass props to layouts in several ways.
 

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

@@ -270,6 +270,26 @@ export default defineNuxtConfig({
 })
 ```
 
+## clientNodePlaceholder
+
+Uses comment nodes (`<!--placeholder-->`) instead of `<div>` elements as placeholders for client-only components during server-side rendering.
+
+When enabled, `.client.vue` components and `createClientOnly()` wrappers render an HTML comment on the server instead of an empty `<div>`. This fixes a Vue hydration issue where scoped styles may not be applied when the placeholder `<div>` and the actual component root share the same tag name.
+
+::warning
+Enabling this means attributes (`class`, `style`, etc.) passed to `.client.vue` components will not appear in the SSR HTML. If you need styled placeholders to prevent layout shift, use `<ClientOnly>` with a `#fallback` slot instead.
+::
+
+This flag is enabled when `future.compatibilityVersion` is set to `5` or higher, but you can also enable it explicitly:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    clientNodePlaceholder: true,
+  },
+})
+```
+
 ## clientFallback
 
 Enables the experimental [`<NuxtClientFallback>`](/docs/4.x/api/components/nuxt-client-fallback) component for rendering content on the client if there's an error in SSR.
@@ -378,7 +398,7 @@ export default defineNuxtConfig({
 
 ## typedPages
 
-Enable the new experimental typed router using [`unplugin-vue-router`](https://github.com/posva/unplugin-vue-router).
+Enable the new experimental typed router.
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -392,14 +412,6 @@ Out of the box, this will enable typed usage of [`navigateTo`](/docs/4.x/api/uti
 
 You can even get typed params within a page by using `const route = useRoute('route-name')`.
 
-::important
-If you use `pnpm` without `shamefully-hoist=true`, you will need to add `unplugin-vue-router` as a hoist pattern in your `pnpm-workspace.yaml` in order for this feature to work.
-```yaml
-publicHoistPattern:
-  - "unplugin-vue-router"
-```
-::
-
 :video-accordion{title="Watch a video from Daniel Roe explaining type-safe routing in Nuxt" videoId="SXk-L19gTZk"}
 
 ## watcher

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

@@ -48,6 +48,10 @@ This is similar to using `v-html` with external content - the remote server can
 The `dangerouslyLoadClientComponents` prop controls an additional layer of risk: whether to also download and execute client components from the remote source. Even with `dangerouslyLoadClientComponents` disabled (the default), you are still trusting the remote server's HTML output.
 ::
 
+::note
+Component props and context are sent as GET query parameters to enable caching. Query parameters may be visible in server access logs, CDN caches, and HTTP `Referer` headers.
+::
+
 ::note
 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" />`.
 ::

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

@@ -87,11 +87,16 @@ This is useful for enforcing settings like authentication headers or a specific
 You can pass a custom `$fetch` instance to `createUseFetch`:
 
 ```ts [app/composables/useAPI.ts]
-export const useAPI = createUseFetch({
+export const useAPI = createUseFetch(callerOptions => ({
   $fetch: useNuxtApp().$api as typeof $fetch,
-})
+  ...callerOptions,
+}))
 ```
 
+::important
+The **function signature** (override mode) is required here so that [`useNuxtApp()`](/docs/4.x/api/composables/use-nuxt-app) is called in the setup context (at the composable call site) rather than in the module scope, where no Nuxt instance is available.
+::
+
 :read-more{to="/docs/4.x/guide/recipes/custom-usefetch"}
 
 :read-more{to="/docs/4.x/api/composables/use-fetch"}

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

@@ -139,6 +139,7 @@ type UseFetchOptions<DataT> = {
   body?: MaybeRefOrGetter<RequestInit['body'] | Record<string, any>>
   headers?: MaybeRefOrGetter<Record<string, string> | [key: string, value: string][] | Headers>
   baseURL?: MaybeRefOrGetter<string>
+  cache?: false | 'default' | 'force-cache' | 'no-cache' | 'no-store' | 'only-if-cached' | 'reload'
   server?: boolean
   lazy?: boolean
   immediate?: boolean
@@ -192,7 +193,7 @@ type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'
 | `body`          | `MaybeRefOrGetter<RequestInit['body'] \| Record<string, any>>`          | -          | Request body. Objects are automatically stringified.                                                             |
 | `headers`       | `MaybeRefOrGetter<Record<string, string> \| [key, value][] \| Headers>` | -          | Request headers.                                                                                                 |
 | `baseURL`       | `MaybeRefOrGetter<string>`                                              | -          | Base URL for the request.                                                                                        |
-| `cache`         | `boolean \| string`                                                     | -          | Cache control. Boolean disables cache, or use Fetch API values: `default`, `no-store`, etc.                      |
+| `cache`         | `false \| string`                                                       | -          | Cache control. Boolean disables cache, or use Fetch API values: `default`, `no-store`, etc.                      |
 | `server`        | `boolean`                                                               | `true`     | Whether to fetch on the server.                                                                                  |
 | `lazy`          | `boolean`                                                               | `false`    | If true, resolves after route loads (does not block navigation).                                                 |
 | `immediate`     | `boolean`                                                               | `true`     | If false, prevents request from firing immediately.                                                              |

package/4.api/5.kit/4.autoimports.md

@@ -118,16 +118,19 @@ import { addImportsSources, defineNuxtModule } from '@nuxt/kit'
 
 export default defineNuxtModule({
   setup () {
-    addImportsSources({
-      from: 'h3',
-      imports: [
-        'defineEventHandler',
-        'getQuery',
-        'getRouterParams',
-        'readBody',
-        'sendRedirect',
-      ],
-    })
+    addImportsSources([
+      { package: '@vueuse/core' },
+      {
+        from: 'h3',
+        imports: [
+          'defineEventHandler',
+          'getQuery',
+          'getRouterParams',
+          'readBody',
+          'sendRedirect',
+        ],
+      },
+    ])
   },
 })
 ```
@@ -135,14 +138,22 @@ export default defineNuxtModule({
 ### Type
 
 ```ts
-function addImportsSources (importSources: ImportSource | ImportSource[]): void
+function addImportsSources (importSources: Preset | Preset[]): void
 ```
 
 ### Parameters
 
 **importSources**: An object or an array of objects with the following properties:
 
+- InlinePreset
+
 | Property  | Type                                        | Required | Description                                                                                    |
 |-----------|---------------------------------------------|----------|------------------------------------------------------------------------------------------------|
 | `from`    | `string`                                    | `true`   | Module specifier to import from.                                                               |
 | `imports` | `PresetImport \| ImportSource[]`{lang="ts"} | `true`   | An object or an array of objects, which can be import names, import objects or import sources. |
+
+- PackagePreset
+
+| Property  | Type                                        | Required | Description                                                                                    |
+|-----------|---------------------------------------------|----------|------------------------------------------------------------------------------------------------|
+| `package` | `string`                                    | `true`   | Name of the package.                                                               |

package/4.api/6.advanced/1.hooks.md

@@ -26,7 +26,7 @@ Check the [app source code](https://github.com/nuxt/nuxt/blob/main/packages/nuxt
 | `link:prefetch`              | `to`                | Client          | Called when a `<NuxtLink>` is observed to be prefetched.                                                                                                                              |
 | `page:start`                 | `pageComponent?`    | Client          | Called on [Suspense](https://vuejs.org/guide/built-ins/suspense#suspense) inside of `NuxtPage` pending event.                                                                         |
 | `page:finish`                | `pageComponent?`    | Client          | Called on [Suspense](https://vuejs.org/guide/built-ins/suspense#suspense) inside of `NuxtPage` resolved event.                                                                        |
-| `page:loading:start`         | -                   | Client          | Called when the `setup()` of the new page is running.                                                                                                                                 |
+| `page:loading:start`         | -                   | Client          | Called when a route navigation begins (before resolution) or when the page key changes. May fire without the page component's `setup()` re-running if the page is reused (e.g. with a static `key` in `definePageMeta`). |
 | `page:loading:end`           | -                   | Client          | Called after `page:finish`                                                                                                                                                            |
 | `page:transition:finish`     | `pageComponent?`    | Client          | After page transition [onAfterLeave](https://vuejs.org/guide/built-ins/transition#javascript-hooks) event.                                                                            |
 | `dev:ssr-logs`               | `logs`              | Client          | Called with an array of server-side logs that have been passed to the client (if `features.devLogs` is enabled).                                                                      |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "4.4.3-29561554.e9b2fa64",
+  "version": "4.4.3-29571486.e4b31efa",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",