@nuxt/docs 4.2.1 → 4.3.0

package/{3.api → 4.api}/2.composables/use-fetch.md

@@ -25,8 +25,8 @@ const { data, status, error, refresh, clear } = await useFetch('/api/modules', {
 </script>
 ```
 
-::warning
-If you're using a custom useFetch wrapper, do not await it in the composable, as that can cause unexpected behavior. Please follow [this recipe](/docs/4.x/guide/recipes/custom-usefetch#custom-usefetchuseasyncdata) for more information on how to make a custom async data fetcher.
+::warning{to="/docs/4.x/guide/recipes/custom-usefetch#custom-usefetchuseasyncdata"}
+If you're using a custom `useFetch` wrapper, do not await it in the composable as that can cause unexpected behavior. See recipe for custom async data fetcher.
 ::
 
 ::note
@@ -183,29 +183,29 @@ type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'
 
 - `options` (object): Configuration for the fetch request. Extends [unjs/ofetch](https://github.com/unjs/ofetch) options and [`AsyncDataOptions`](/docs/4.x/api/composables/use-async-data#params). All options can be a static value, a `ref`, or a computed value.
 
-| Option | Type | Default | Description |
-| ---| --- | --- | --- |
-| `key` | `MaybeRefOrGetter<string>` | auto-gen | Unique key for de-duplication. If not provided, generated from URL and options. |
-| `method` | `MaybeRefOrGetter<string>` | `'GET'` | HTTP request method. |
-| `query` | `MaybeRefOrGetter<SearchParams>` | - | Query/search params to append to the URL. Alias: `params`. |
-| `params` | `MaybeRefOrGetter<SearchParams>` | - | Alias for `query`. |
-| `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. |
-| `timeout` | `MaybeRefOrGetter<number>` | - | Timeout in milliseconds to abort the request. |
-| `cache` | `boolean \| 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. |
-| `default` | `() => DataT` | - | Factory for default value of `data` before async resolves. |
-| `timeout` | `number` | - | A number in milliseconds to wait before timing out the request (defaults to `undefined`, which means no timeout) |
-| `transform` | `(input: DataT) => DataT \| Promise<DataT>` | - | Function to transform the result after resolving. |
-| `getCachedData`| `(key, nuxtApp, ctx) => DataT \| undefined` | - | Function to return cached data. See below for default. |
-| `pick` | `string[]` | - | Only pick specified keys from the result. |
-| `watch` | `MultiWatchSources \| false` | - | Array of reactive sources to watch and auto-refresh. `false` disables watching. |
-| `deep` | `boolean` | `false` | Return data in a deep ref object. |
-| `dedupe` | `'cancel' \| 'defer'` | `'cancel'` | Avoid fetching same key more than once at a time. |
-| `$fetch` | `typeof globalThis.$fetch` | - | Custom $fetch implementation. See [Custom useFetch in Nuxt](/docs/4.x/guide/recipes/custom-usefetch) |
+| Option          | Type                                                                    | Default    | Description                                                                                                      |
+|-----------------|-------------------------------------------------------------------------|------------|------------------------------------------------------------------------------------------------------------------|
+| `key`           | `MaybeRefOrGetter<string>`                                              | auto-gen   | Unique key for de-duplication. If not provided, generated from URL and options.                                  |
+| `method`        | `MaybeRefOrGetter<string>`                                              | `'GET'`    | HTTP request method.                                                                                             |
+| `query`         | `MaybeRefOrGetter<SearchParams>`                                        | -          | Query/search params to append to the URL. Alias: `params`.                                                       |
+| `params`        | `MaybeRefOrGetter<SearchParams>`                                        | -          | Alias for `query`.                                                                                               |
+| `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.                                                                                        |
+| `timeout`       | `MaybeRefOrGetter<number>`                                              | -          | Timeout in milliseconds to abort the request.                                                                    |
+| `cache`         | `boolean \| 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.                                                              |
+| `default`       | `() => DataT`                                                           | -          | Factory for default value of `data` before async resolves.                                                       |
+| `timeout`       | `number`                                                                | -          | A number in milliseconds to wait before timing out the request (defaults to `undefined`, which means no timeout) |
+| `transform`     | `(input: DataT) => DataT \| Promise<DataT>`                             | -          | Function to transform the result after resolving.                                                                |
+| `getCachedData` | `(key, nuxtApp, ctx) => DataT \| undefined`                             | -          | Function to return cached data. See below for default.                                                           |
+| `pick`          | `string[]`                                                              | -          | Only pick specified keys from the result.                                                                        |
+| `watch`         | `MultiWatchSources \| false`                                            | -          | Array of reactive sources to watch and auto-refresh. `false` disables watching.                                  |
+| `deep`          | `boolean`                                                               | `false`    | Return data in a deep ref object.                                                                                |
+| `dedupe`        | `'cancel' \| 'defer'`                                                   | `'cancel'` | Avoid fetching same key more than once at a time.                                                                |
+| `$fetch`        | `typeof globalThis.$fetch`                                              | -          | Custom $fetch implementation. See [Custom useFetch in Nuxt](/docs/4.x/guide/recipes/custom-usefetch)             |
 
 ::note
 All fetch options can be given a `computed` or `ref` value. These will be watched and new requests made automatically with any new values if they are updated.
@@ -222,14 +222,14 @@ This only caches data when `experimental.payloadExtraction` in `nuxt.config` is
 
 ## Return Values
 
-| Name | Type | Description |
-| --- | --- |--- |
-| `data` | `Ref<DataT \| undefined>` | The result of the asynchronous fetch. |
-| `refresh` | `(opts?: AsyncDataExecuteOptions) => Promise<void>` | Function to manually refresh the data. By default, Nuxt waits until a `refresh` is finished before it can be executed again. |
-| `execute` | `(opts?: AsyncDataExecuteOptions) => Promise<void>` | Alias for `refresh`. |
-| `error` | `Ref<ErrorT \| undefined>` | Error object if the data fetching failed. |
-| `status` | `Ref<'idle' \| 'pending' \| 'success' \| 'error'>` | Status of the data request. See below for possible values. |
-| `clear` | `() => void` | Resets `data` to `undefined` (or the value of `options.default()` if provided), `error` to `undefined`, set `status` to `idle`, and cancels any pending requests. |
+| Name      | Type                                                | Description                                                                                                                                                       |
+|-----------|-----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `data`    | `Ref<DataT \| undefined>`                           | The result of the asynchronous fetch.                                                                                                                             |
+| `refresh` | `(opts?: AsyncDataExecuteOptions) => Promise<void>` | Function to manually refresh the data. By default, Nuxt waits until a `refresh` is finished before it can be executed again.                                      |
+| `execute` | `(opts?: AsyncDataExecuteOptions) => Promise<void>` | Alias for `refresh`.                                                                                                                                              |
+| `error`   | `Ref<ErrorT \| undefined>`                          | Error object if the data fetching failed.                                                                                                                         |
+| `status`  | `Ref<'idle' \| 'pending' \| 'success' \| 'error'>`  | Status of the data request. See below for possible values.                                                                                                        |
+| `clear`   | `() => void`                                        | Resets `data` to `undefined` (or the value of `options.default()` if provided), `error` to `undefined`, set `status` to `idle`, and cancels any pending requests. |
 
 ### Status values
 

package/{3.api → 4.api}/2.composables/use-head.md

@@ -38,7 +38,7 @@ The properties of `useHead` can be dynamic, accepting `ref`, `computed` and `rea
 ## Type
 
 ```ts [Signature]
-export function useHead (meta: MaybeComputedRef<MetaObject>): void
+export function useHead (meta: MaybeComputedRef<MetaObject>): ActiveHeadEntry<UseHeadInput>
 
 interface MetaObject {
   title?: string
@@ -52,6 +52,21 @@ interface MetaObject {
   htmlAttrs?: HtmlAttributes
   bodyAttrs?: BodyAttributes
 }
+
+interface ActiveHeadEntry<Input> {
+  /**
+   * Updates the entry with new input.
+   *
+   * Will first clear any side effects for previous input.
+   */
+  patch: (input: Input) => void
+  /**
+   * Dispose the entry, removing it from the active head.
+   *
+   * Will queue side effects for removal.
+   */
+  dispose: () => void
+}
 ```
 
 See [@unhead/schema](https://github.com/unjs/unhead/blob/main/packages/vue/src/types/schema.ts) for more detailed types.

package/{3.api → 4.api}/2.composables/use-lazy-fetch.md

@@ -69,14 +69,14 @@ export function useLazyFetch<DataT, ErrorT> (
 
 Returns the same `AsyncData` object as [`useFetch`](/docs/4.x/api/composables/use-fetch):
 
-| Name | Type | Description |
-| --- | --- |--- |
-| `data` | `Ref<DataT \| undefined>` | The result of the asynchronous fetch. |
-| `refresh` | `(opts?: AsyncDataExecuteOptions) => Promise<void>` | Function to manually refresh the data. |
-| `execute` | `(opts?: AsyncDataExecuteOptions) => Promise<void>` | Alias for `refresh`. |
-| `error` | `Ref<ErrorT \| undefined>` | Error object if the data fetching failed. |
-| `status` | `Ref<'idle' \| 'pending' \| 'success' \| 'error'>` | Status of the data request. |
-| `clear` | `() => void` | Resets `data` to `undefined`, `error` to `undefined`, sets `status` to `idle`, and cancels any pending requests. |
+| Name      | Type                                                | Description                                                                                                      |
+|-----------|-----------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
+| `data`    | `Ref<DataT \| undefined>`                           | The result of the asynchronous fetch.                                                                            |
+| `refresh` | `(opts?: AsyncDataExecuteOptions) => Promise<void>` | Function to manually refresh the data.                                                                           |
+| `execute` | `(opts?: AsyncDataExecuteOptions) => Promise<void>` | Alias for `refresh`.                                                                                             |
+| `error`   | `Ref<ErrorT \| undefined>`                          | Error object if the data fetching failed.                                                                        |
+| `status`  | `Ref<'idle' \| 'pending' \| 'success' \| 'error'>`  | Status of the data request.                                                                                      |
+| `clear`   | `() => void`                                        | Resets `data` to `undefined`, `error` to `undefined`, sets `status` to `idle`, and cancels any pending requests. |
 
 :read-more{to="/docs/4.x/api/composables/use-fetch#return-values"}
 

package/{3.api → 4.api}/2.composables/use-nuxt-app.md

@@ -30,7 +30,7 @@ By default, the shared runtime context of Nuxt is namespaced under the [`buildId
 
 ### `provide (name, value)`
 
-`nuxtApp` is a runtime context that you can extend using [Nuxt plugins](/docs/4.x/guide/directory-structure/app/plugins). Use the `provide` function to create Nuxt plugins to make values and helper methods available in your Nuxt application across all composables and components.
+`nuxtApp` is a runtime context that you can extend using [Nuxt plugins](/docs/4.x/directory-structure/app/plugins). Use the `provide` function to create Nuxt plugins to make values and helper methods available in your Nuxt application across all composables and components.
 
 `provide` function accepts `name` and `value` parameters.
 
@@ -46,7 +46,7 @@ As you can see in the example above, `$hello` has become the new and custom part
 
 ### `hook(name, cb)`
 
-Hooks available in `nuxtApp` allows you to customize the runtime aspects of your Nuxt application. You can use runtime hooks in Vue.js composables and [Nuxt plugins](/docs/4.x/guide/directory-structure/app/plugins) to hook into the rendering lifecycle.
+Hooks available in `nuxtApp` allows you to customize the runtime aspects of your Nuxt application. You can use runtime hooks in Vue.js composables and [Nuxt plugins](/docs/4.x/directory-structure/app/plugins) to hook into the rendering lifecycle.
 
 `hook` function is useful for adding custom logic by hooking into the rendering lifecycle at a specific point. `hook` function is mostly used when creating Nuxt plugins.
 
@@ -84,8 +84,8 @@ await nuxtApp.callHook('my-plugin:init')
 
 Some useful methods:
 - [`component()`](https://vuejs.org/api/application#app-component) - Registers a global component if passing both a name string and a component definition, or retrieves an already registered one if only the name is passed.
-- [`directive()`](https://vuejs.org/api/application#app-directive) - Registers a global custom directive if passing both a name string and a directive definition, or retrieves an already registered one if only the name is passed[(example)](/docs/4.x/guide/directory-structure/app/plugins#vue-directives).
-- [`use()`](https://vuejs.org/api/application#app-use) - Installs a **[Vue.js Plugin](https://vuejs.org/guide/reusability/plugins)** [(example)](/docs/4.x/guide/directory-structure/app/plugins#vue-plugins).
+- [`directive()`](https://vuejs.org/api/application#app-directive) - Registers a global custom directive if passing both a name string and a directive definition, or retrieves an already registered one if only the name is passed[(example)](/docs/4.x/directory-structure/app/plugins#vue-directives).
+- [`use()`](https://vuejs.org/api/application#app-use) - Installs a **[Vue.js Plugin](https://vuejs.org/guide/reusability/plugins)** [(example)](/docs/4.x/directory-structure/app/plugins#vue-plugins).
 
 :read-more{icon="i-simple-icons-vuedotjs" to="https://vuejs.org/api/application.html#application-api"}
 
@@ -136,6 +136,8 @@ Nuxt exposes the following properties through `ssrContext`:
 
   It is also possible to use more advanced types, such as `ref`, `reactive`, `shallowRef`, `shallowReactive` and `NuxtError`.
 
+#### Custom Reducer/Reviver
+
   Since [Nuxt v3.4](https://nuxt.com/blog/v3-4#payload-enhancements), it is possible to define your own reducer/reviver for types that are not supported by Nuxt.
 
   :video-accordion{title="Watch a video from Alexander Lichter about serializing payloads, especially with regards to classes" videoId="8w6ffRBs8a4"}

package/{3.api → 4.api}/2.composables/use-response-header.md

@@ -37,7 +37,7 @@ header.value = 'my-value'
 </template>
 ```
 
-We can use `useResponseHeader` for example in Nuxt [middleware](/docs/4.x/guide/directory-structure/app/middleware) to set a response header for all pages.
+We can use `useResponseHeader` for example in Nuxt [middleware](/docs/4.x/directory-structure/app/middleware) to set a response header for all pages.
 
 ```ts [app/middleware/my-header-middleware.ts]
 export default defineNuxtRouteMiddleware((to, from) => {

package/{3.api → 4.api}/2.composables/use-route-announcer.md

@@ -1,8 +1,6 @@
 ---
 title: 'useRouteAnnouncer'
 description: This composable observes the page title changes and updates the announcer message accordingly.
-navigation:
-  badge: New
 links:
   - label: Source
     icon: i-simple-icons-github

package/{3.api → 4.api}/2.composables/use-route.md

@@ -76,7 +76,7 @@ The `useRoute()` composable should only be used in the setup function of a Vue c
 This applies to any composable that uses `useRoute()` internally too.
 ::
 
-::read-more{to="/docs/4.x/guide/directory-structure/app/middleware"}
+::read-more{to="/docs/4.x/directory-structure/app/middleware"}
 Read more about accessing the route in the middleware section.
 ::
 

package/{3.api → 4.api}/2.composables/use-router.md

@@ -49,7 +49,7 @@ router.resolve({ name: 'home' })
 ```
 
 ::note
-`router.addRoute()` adds route details into an array of routes and it is useful while building [Nuxt plugins](/docs/4.x/guide/directory-structure/app/plugins) while `router.push()` on the other hand, triggers a new navigation immediately and it is useful in pages, Vue components and composable.
+`router.addRoute()` adds route details into an array of routes and it is useful while building [Nuxt plugins](/docs/4.x/directory-structure/app/plugins) while `router.push()` on the other hand, triggers a new navigation immediately and it is useful in pages, Vue components and composable.
 ::
 
 ## Based on History API
@@ -80,7 +80,7 @@ Read more about the browser's History API.
 
 However, Nuxt has a concept of **route middleware** that simplifies the implementation of navigation guards and provides a better developer experience.
 
-:read-more{to="/docs/4.x/guide/directory-structure/app/middleware"}
+:read-more{to="/docs/4.x/directory-structure/app/middleware"}
 
 ## Promise and Error Handling
 

package/{3.api → 4.api}/2.composables/use-runtime-config.md

@@ -95,7 +95,7 @@ Any environment variables set within `.env` file are accessed using `process.env
 In **production runtime**, you should use platform environment variables and `.env` is not used.
 ::
 
-:read-more{to="/docs/4.x/guide/directory-structure/env"}
+:read-more{to="/docs/4.x/directory-structure/env"}
 
 ## `app` namespace
 

package/{3.api → 4.api}/2.composables/use-state.md

@@ -46,3 +46,13 @@ export function useState<T> (key: string, init?: () => T | Ref<T>): Ref<T>
 - `key`: A unique key ensuring that data fetching is properly de-duplicated across requests. If you do not provide a key, then a key that is unique to the file and line number of the instance of [`useState`](/docs/4.x/api/composables/use-state) will be generated for you.
 - `init`: A function that provides initial value for the state when not initiated. This function can also return a `Ref`.
 - `T`: (typescript only) Specify the type of state
+
+## Troubleshooting
+
+### `Cannot stringify arbitrary non-POJOs`
+
+This error occurs when you try to store a non-serializable payload with `useState`, such as class instances.
+
+If you want to store class instances with `useState` that are not supported by Nuxt, you can use [`definePayloadPlugin`](/docs/4.x/api/composables/use-nuxt-app#custom-reducerreviver) to add a custom serializer and deserializer for your classes.
+
+:read-more{to="/docs/4.x/api/composables/use-nuxt-app#payload"}

package/{3.api → 4.api}/3.utils/$fetch.md

@@ -11,7 +11,7 @@ links:
 Nuxt uses [ofetch](https://github.com/unjs/ofetch) to expose globally the `$fetch` helper for making HTTP requests within your Vue app or API routes.
 
 ::tip{icon="i-lucide-rocket"}
-During server-side rendering, calling `$fetch` to fetch your internal [API routes](/docs/4.x/guide/directory-structure/server) will directly call the relevant function (emulating the request), **saving an additional API call**.
+During server-side rendering, calling `$fetch` to fetch your internal [API routes](/docs/4.x/directory-structure/server) will directly call the relevant function (emulating the request), **saving an additional API call**.
 ::
 
 ::note{color="blue" icon="i-lucide-info"}

package/{3.api → 4.api}/3.utils/abort-navigation.md

@@ -9,7 +9,7 @@ links:
 ---
 
 ::warning
-`abortNavigation` is only usable inside a [route middleware handler](/docs/4.x/guide/directory-structure/app/middleware).
+`abortNavigation` is only usable inside a [route middleware handler](/docs/4.x/directory-structure/app/middleware).
 ::
 
 ## Type

package/{3.api → 4.api}/3.utils/add-route-middleware.md

@@ -9,7 +9,7 @@ links:
 ---
 
 ::note
-Route middleware are navigation guards stored in the [`app/middleware/`](/docs/4.x/guide/directory-structure/app/middleware) directory of your Nuxt application (unless [set otherwise](/docs/4.x/api/nuxt-config#middleware)).
+Route middleware are navigation guards stored in the [`app/middleware/`](/docs/4.x/directory-structure/app/middleware) directory of your Nuxt application (unless [set otherwise](/docs/4.x/api/nuxt-config#middleware)).
 ::
 
 ## Type

package/{3.api → 4.api}/3.utils/call-once.md

@@ -1,8 +1,6 @@
 ---
 title: "callOnce"
 description: "Run a given function or block of code once during SSR or CSR."
-navigation:
-  badge: New
 links:
   - label: Source
     icon: i-simple-icons-github

package/{3.api → 4.api}/3.utils/create-error.md

@@ -12,9 +12,9 @@ You can use this function to create an error object with additional metadata. It
 
 ## Parameters
 
-- `err`: `string | { cause, data, message, name, stack, statusCode, statusMessage, fatal }`
+- `err`: `string | { cause, data, message, name, stack, status, statusText, fatal }`
 
-You can pass either a string or an object to the `createError` function. If you pass a string, it will be used as the error `message`, and the `statusCode` will default to `500`. If you pass an object, you can set multiple properties of the error, such as `statusCode`, `message`, and other error properties.
+You can pass either a string or an object to the `createError` function. If you pass a string, it will be used as the error `message`, and the `status` will default to `500`. If you pass an object, you can set multiple properties of the error, such as `status`, `message`, and other error properties.
 
 ## In Vue App
 
@@ -30,7 +30,7 @@ If you throw an error created with `createError`:
 const route = useRoute()
 const { data } = await useFetch(`/api/movies/${route.params.slug}`)
 if (!data.value) {
-  throw createError({ statusCode: 404, statusMessage: 'Page Not Found' })
+  throw createError({ status: 404, statusText: 'Page Not Found' })
 }
 </script>
 ```
@@ -44,12 +44,12 @@ Use `createError` to trigger error handling in server API routes.
 ```ts [server/api/error.ts]
 export default eventHandler(() => {
   throw createError({
-    statusCode: 404,
-    statusMessage: 'Page Not Found',
+    status: 404,
+    statusText: 'Page Not Found',
   })
 })
 ```
 
-In API routes, using `createError` by passing an object with a short `statusMessage` is recommended because it can be accessed on the client side. Otherwise, a `message` passed to `createError` on an API route will not propagate to the client. Alternatively, you can use the `data` property to pass data back to the client. In any case, always consider avoiding to put dynamic user input to the message to avoid potential security issues.
+In API routes, using `createError` by passing an object with a short `statusText` is recommended because it can be accessed on the client side. Otherwise, a `message` passed to `createError` on an API route will not propagate to the client. Alternatively, you can use the `data` property to pass data back to the client. In any case, always consider avoiding to put dynamic user input to the message to avoid potential security issues.
 
 :read-more{to="/docs/4.x/getting-started/error-handling"}

package/{3.api → 4.api}/3.utils/define-nuxt-plugin.md

@@ -16,7 +16,7 @@ export default defineNuxtPlugin((nuxtApp) => {
 })
 ```
 
-:read-more{to="/docs/4.x/guide/directory-structure/app/plugins#creating-plugins"}
+:read-more{to="/docs/4.x/directory-structure/app/plugins#creating-plugins"}
 
 ## Type
 
@@ -42,19 +42,19 @@ interface ObjectPlugin<T> {
 ## Parameters
 
 **plugin**: A plugin can be defined in two ways:
-1. **Function Plugin**: A function that receives the [`NuxtApp`](/docs/4.x/guide/going-further/internals#the-nuxtapp-interface) instance and can return a promise with a potential object with a [`provide`](/docs/4.x/guide/directory-structure/app/plugins#providing-helpers) property if you want to provide a helper on [`NuxtApp`](/docs/4.x/guide/going-further/internals#the-nuxtapp-interface) instance.
+1. **Function Plugin**: A function that receives the [`NuxtApp`](/docs/4.x/guide/going-further/internals#the-nuxtapp-interface) instance and can return a promise with a potential object with a [`provide`](/docs/4.x/directory-structure/app/plugins#providing-helpers) property if you want to provide a helper on [`NuxtApp`](/docs/4.x/guide/going-further/internals#the-nuxtapp-interface) instance.
 2. **Object Plugin**: An object that can include various properties to configure the plugin's behavior, such as `name`, `enforce`, `dependsOn`, `order`, `parallel`, `setup`, `hooks`, and `env`.
 
-| Property           | Type                                                                 | Required | Description                                                                                                     |
-| ------------------ | -------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
-| `name` | `string` | `false` | Optional name for the plugin, useful for debugging and dependency management. |
-| `enforce` | `'pre'` \| `'default'` \| `'post'` | `false` | Controls when the plugin runs relative to other plugins. |
-| `dependsOn` | `string[]` | `false` | Array of plugin names this plugin depends on. Ensures proper execution order. |
-| `order` | `number` | `false` | This allows more granular control over plugin order and should only be used by advanced users. **It overrides the value of `enforce` and is used to sort plugins.** |
-| `parallel` | `boolean` | `false` | Whether to execute the plugin in parallel with other parallel plugins. |
-| `setup` | `Plugin<T>`{lang="ts"}  | `false` | The main plugin function, equivalent to a function plugin. |
-| `hooks` | `Partial<RuntimeNuxtHooks>`{lang="ts"}  | `false` | Nuxt app runtime hooks to register directly. |
-| `env` | `{ islands?: boolean }`{lang="ts"}  | `false` | Set this value to `false` if you don't want the plugin to run when rendering server-only or island components. |
+| Property    | Type                                   | Required | Description                                                                                                                                                         |
+|-------------|----------------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `name`      | `string`                               | `false`  | Optional name for the plugin, useful for debugging and dependency management.                                                                                       |
+| `enforce`   | `'pre'` \| `'default'` \| `'post'`     | `false`  | Controls when the plugin runs relative to other plugins.                                                                                                            |
+| `dependsOn` | `string[]`                             | `false`  | Array of plugin names this plugin depends on. Ensures proper execution order.                                                                                       |
+| `order`     | `number`                               | `false`  | This allows more granular control over plugin order and should only be used by advanced users. **It overrides the value of `enforce` and is used to sort plugins.** |
+| `parallel`  | `boolean`                              | `false`  | Whether to execute the plugin in parallel with other parallel plugins.                                                                                              |
+| `setup`     | `Plugin<T>`{lang="ts"}                 | `false`  | The main plugin function, equivalent to a function plugin.                                                                                                          |
+| `hooks`     | `Partial<RuntimeNuxtHooks>`{lang="ts"} | `false`  | Nuxt app runtime hooks to register directly.                                                                                                                        |
+| `env`       | `{ islands?: boolean }`{lang="ts"}     | `false`  | Set this value to `false` if you don't want the plugin to run when rendering server-only or island components.                                                      |
 
 :video-accordion{title="Watch a video from Alexander Lichter about the Object Syntax for Nuxt plugins" videoId="2aXZyXB1QGQ"}
 

package/{3.api → 4.api}/3.utils/define-nuxt-route-middleware.md

@@ -8,7 +8,7 @@ links:
     size: xs
 ---
 
-Route middleware are stored in the [`app/middleware/`](/docs/4.x/guide/directory-structure/app/middleware) of your Nuxt application (unless [set otherwise](/docs/4.x/api/nuxt-config#middleware)).
+Route middleware are stored in the [`app/middleware/`](/docs/4.x/directory-structure/app/middleware) of your Nuxt application (unless [set otherwise](/docs/4.x/api/nuxt-config#middleware)).
 
 ## Type
 
@@ -39,7 +39,7 @@ You can use route middleware to throw errors and show helpful error messages:
 ```ts [app/middleware/error.ts]
 export default defineNuxtRouteMiddleware((to) => {
   if (to.params.id === '1') {
-    throw createError({ statusCode: 404, statusMessage: 'Page Not Found' })
+    throw createError({ status: 404, statusText: 'Page Not Found' })
   }
 })
 ```

package/{3.api → 4.api}/3.utils/define-page-meta.md

@@ -8,7 +8,7 @@ links:
     size: xs
 ---
 
-`definePageMeta` is a compiler macro that you can use to set metadata for your **page** components located in the [`app/pages/`](/docs/4.x/guide/directory-structure/app/pages) directory (unless [set otherwise](/docs/4.x/api/nuxt-config#pages)). This way you can set custom metadata for each static or dynamic route of your Nuxt application.
+`definePageMeta` is a compiler macro that you can use to set metadata for your **page** components located in the [`app/pages/`](/docs/4.x/directory-structure/app/pages) directory (unless [set otherwise](/docs/4.x/api/nuxt-config#pages)). This way you can set custom metadata for each static or dynamic route of your Nuxt application.
 
 ```vue [app/pages/some-page.vue]
 <script setup lang="ts">
@@ -18,7 +18,7 @@ definePageMeta({
 </script>
 ```
 
-:read-more{to="/docs/4.x/guide/directory-structure/app/pages#page-metadata"}
+:read-more{to="/docs/4.x/directory-structure/app/pages#page-metadata"}
 
 ## Type
 
@@ -32,6 +32,7 @@ interface PageMeta {
   path?: string
   props?: RouteRecordRaw['props']
   alias?: string | string[]
+  groups?: string[]
   pageTransition?: boolean | TransitionProps
   layoutTransition?: boolean | TransitionProps
   viewTransition?: boolean | 'always'
@@ -56,7 +57,7 @@ interface PageMeta {
 
   - **Type**: `string`
 
-    You may define a name for this page's route. By default, name is generated based on path inside the [`app/pages/` directory](/docs/4.x/guide/directory-structure/app/pages).
+    You may define a name for this page's route. By default, name is generated based on path inside the [`app/pages/` directory](/docs/4.x/directory-structure/app/pages).
 
   **`path`**
 
@@ -76,6 +77,12 @@ interface PageMeta {
 
     Aliases for the record. Allows defining extra paths that will behave like a copy of the record. Allows having paths shorthands like `/users/:id` and `/u/:id`. All `alias` and `path` values must share the same params.
 
+  **`groups`**
+
+  - **Type**: `string[]`
+
+    Route groups the page belongs to, based on the folder structure. Automatically populated for pages within [route groups](/docs/4.x/guide/directory-structure/app/pages#route-groups).
+
   **`keepalive`**
 
   - **Type**: `boolean` | [`KeepAliveProps`](https://vuejs.org/api/built-in-components#keepalive)
@@ -104,7 +111,7 @@ interface PageMeta {
 
   - **Type**: `MiddlewareKey` | [`NavigationGuard`](https://router.vuejs.org/api/interfaces/navigationguard) | `Array<MiddlewareKey | NavigationGuard>`
 
-    Define anonymous or named middleware directly within `definePageMeta`. Learn more about [route middleware](/docs/4.x/guide/directory-structure/app/middleware).
+    Define anonymous or named middleware directly within `definePageMeta`. Learn more about [route middleware](/docs/4.x/directory-structure/app/middleware).
 
   **`pageTransition`**
 
@@ -130,7 +137,7 @@ interface PageMeta {
 
   - **Type**: `(route: RouteLocationNormalized) => boolean | Promise<boolean> | Partial<NuxtError> | Promise<Partial<NuxtError>>`
 
-    Validate whether a given route can validly be rendered with this page. Return true if it is valid, or false if not. If another match can't be found, this will mean a 404. You can also directly return an object with `statusCode`/`statusMessage` to respond immediately with an error (other matches will not be checked).
+    Validate whether a given route can validly be rendered with this page. Return true if it is valid, or false if not. If another match can't be found, this will mean a 404. You can also directly return an object with `status`/`statusText` to respond immediately with an error (other matches will not be checked).
 
   **`scrollToTop`**
 
@@ -142,7 +149,7 @@ interface PageMeta {
 
   - **Type**: `any`
 
-    Apart from the above properties, you can also set **custom** metadata. You may wish to do so in a type-safe way by [augmenting the type of the `meta` object](/docs/4.x/guide/directory-structure/app/pages/#typing-custom-metadata).
+    Apart from the above properties, you can also set **custom** metadata. You may wish to do so in a type-safe way by [augmenting the type of the `meta` object](/docs/4.x/directory-structure/app/pages/#typing-custom-metadata).
 
 ## Examples
 
@@ -219,7 +226,7 @@ For more examples see [Vue Router's Matching Syntax](https://router.vuejs.org/gu
 
 ### Defining Layout
 
-You can define the layout that matches the layout's file name located (by default) in the [`app/layouts/` directory](/docs/4.x/guide/directory-structure/app/layouts). You can also disable the layout by setting the `layout` to `false`:
+You can define the layout that matches the layout's file name located (by default) in the [`app/layouts/` directory](/docs/4.x/directory-structure/app/layouts). You can also disable the layout by setting the `layout` to `false`:
 
 ```vue [app/pages/some-page.vue]
 <script setup lang="ts">

package/{3.api → 4.api}/3.utils/navigate-to.md

@@ -68,7 +68,7 @@ export default defineNuxtRouteMiddleware((to, from) => {
 
 In this case, `navigateTo` will be executed but not returned, which may lead to unexpected behavior.
 
-:read-more{to="/docs/4.x/guide/directory-structure/app/middleware"}
+:read-more{to="/docs/4.x/directory-structure/app/middleware"}
 
 ### Navigating to an External URL
 
@@ -217,14 +217,14 @@ An object accepting the following properties:
 
     - An object accepting the following properties:
 
-      | Property | Type    | Description |
-      |----------|---------|--------------|
-      | `popup`  | `boolean` | Requests a minimal popup window instead of a new tab, with UI features decided by the browser. |
-      | `width` or `innerWidth`  | `number`  | Specifies the content area's width (minimum 100 pixels), including scrollbars. |
-      | `height` or `innerHeight` | `number`  | Specifies the content area's height (minimum 100 pixels), including scrollbars. |
-      | `left` or `screenX`   | `number`  | Sets the horizontal position of the new window relative to the left edge of the screen. |
-      | `top` or `screenY`   | `number`  | Sets the vertical position of the new window relative to the top edge of the screen. |
-      | `noopener` | `boolean` | Prevents the new window from accessing the originating window via `window.opener`. |
-      | `noreferrer` | `boolean` | Prevents the Referer header from being sent and implicitly enables `noopener`. |
+      | Property                  | Type      | Description                                                                                    |
+      |---------------------------|-----------|------------------------------------------------------------------------------------------------|
+      | `popup`                   | `boolean` | Requests a minimal popup window instead of a new tab, with UI features decided by the browser. |
+      | `width` or `innerWidth`   | `number`  | Specifies the content area's width (minimum 100 pixels), including scrollbars.                 |
+      | `height` or `innerHeight` | `number`  | Specifies the content area's height (minimum 100 pixels), including scrollbars.                |
+      | `left` or `screenX`       | `number`  | Sets the horizontal position of the new window relative to the left edge of the screen.        |
+      | `top` or `screenY`        | `number`  | Sets the vertical position of the new window relative to the top edge of the screen.           |
+      | `noopener`                | `boolean` | Prevents the new window from accessing the originating window via `window.opener`.             |
+      | `noreferrer`              | `boolean` | Prevents the Referer header from being sent and implicitly enables `noopener`.                 |
 
       Refer to the [documentation](https://developer.mozilla.org/en-US/docs/Web/API/Window/open#windowfeatures) for more detailed information on the **windowFeatures** properties.

package/{3.api → 4.api}/3.utils/refresh-cookie.md

@@ -1,8 +1,6 @@
 ---
 title: "refreshCookie"
 description: "Refresh useCookie values manually when a cookie has changed"
-navigation:
-  badge: New
 links:
   - label: Source
     icon: i-simple-icons-github

package/{3.api → 4.api}/3.utils/set-page-layout.md

@@ -19,6 +19,42 @@ export default defineNuxtRouteMiddleware((to) => {
 })
 ```
 
+## Passing Props to Layouts
+
+You can pass props to the layout by providing an object as the second argument:
+
+```ts [app/middleware/admin-layout.ts]
+export default defineNuxtRouteMiddleware((to) => {
+  setPageLayout('admin', {
+    sidebar: true,
+    title: 'Dashboard',
+  })
+})
+```
+
+The layout can then receive these props:
+
+```vue [app/layouts/admin.vue]
+<script setup lang="ts">
+const props = defineProps<{
+  sidebar?: boolean
+  title?: string
+}>()
+</script>
+
+<template>
+  <div>
+    <aside v-if="sidebar">
+      Sidebar
+    </aside>
+    <main>
+      <h1>{{ title }}</h1>
+      <slot />
+    </main>
+  </div>
+</template>
+```
+
 ::note
 If you choose to set the layout dynamically on the server side, you _must_ do so before the layout is rendered by Vue (that is, within a plugin or route middleware) to avoid a hydration mismatch.
 ::

package/{3.api → 4.api}/3.utils/set-response-status.md

@@ -1,6 +1,6 @@
 ---
 title: 'setResponseStatus'
-description: setResponseStatus sets the statusCode (and optionally the statusMessage) of the response.
+description: setResponseStatus sets the status (and optionally the statusText) of the response.
 links:
   - label: Source
     icon: i-simple-icons-github
@@ -10,7 +10,7 @@ links:
 
 Nuxt provides composables and utilities for first-class server-side-rendering support.
 
-`setResponseStatus` sets the statusCode (and optionally the statusMessage) of the response.
+`setResponseStatus` sets the status (and optionally the statusText) of the response.
 
 ::important
 `setResponseStatus` can only be called in the [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-context).