@nuxt/docs 3.20.1 → 3.21.0

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

@@ -0,0 +1,183 @@
+---
+title: 'useCookie'
+description: useCookie is an SSR-friendly composable to read and write cookies.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/cookie.ts
+    size: xs
+---
+
+## Usage
+
+Within your pages, components, and plugins, you can use `useCookie` to read and write cookies in an SSR-friendly way.
+
+```ts
+const cookie = useCookie(name, options)
+```
+
+::note
+`useCookie` only works in the [Nuxt context](/docs/3.x/guide/going-further/nuxt-app#the-nuxt-context).
+::
+
+::tip
+The returned ref will automatically serialize and deserialize cookie values to JSON.
+::
+
+## Type
+
+```ts [Signature]
+import type { Ref } from 'vue'
+import type { CookieParseOptions, CookieSerializeOptions } from 'cookie-es'
+
+export interface CookieOptions<T = any> extends Omit<CookieSerializeOptions & CookieParseOptions, 'decode' | 'encode'> {
+  decode?(value: string): T
+  encode?(value: T): string
+  default?: () => T | Ref<T>
+  watch?: boolean | 'shallow'
+  readonly?: boolean
+}
+
+export interface CookieRef<T> extends Ref<T> {}
+
+export function useCookie<T = string | null | undefined> (
+  name: string,
+  options?: CookieOptions<T>,
+): CookieRef<T>
+```
+
+## Parameters
+
+`name`: The name of the cookie.
+
+`options`: Options to control cookie behavior. The object can have the following properties:
+
+Most of the options will be directly passed to the [cookie](https://github.com/jshttp/cookie) package.
+
+| Property      | Type                   | Default                                                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+|---------------|------------------------|----------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `decode`      | `(value: string) => T` | `decodeURIComponent` + [destr](https://github.com/unjs/destr). | Custom function to decode the cookie value.  Since the value of a cookie has a limited character set (and must be a simple string), this function can be used to decode a previously encoded cookie value into a JavaScript string or other object. <br/> **Note:** If an error is thrown from this function, the original, non-decoded cookie value will be returned as the cookie's value.                                                                                                                                                                                                                                                       |
+| `encode`      | `(value: T) => string` | `JSON.stringify` + `encodeURIComponent`                        | Custom function to encode the cookie value. Since the value of a cookie has a limited character set (and must be a simple string), this function can be used to encode a value into a string suited for a cookie's value.                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `default`     | `() => T \| Ref<T>`    | `undefined`                                                    | Function returning the default value if the cookie does not exist.  The function can also return a `Ref`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `watch`       | `boolean \| 'shallow'` | `true`                                                         | Whether to watch for changes and update the cookie. `true` for deep watch, `'shallow'` for shallow watch, i.e. data changes for only top level properties, `false` to disable. <br/> **Note:** Refresh `useCookie` values manually when a cookie has changed with [`refreshCookie`](/docs/3.x/api/utils/refresh-cookie).                                                                                                                                                                                                                                                                                                                           |
+| `readonly`    | `boolean`              | `false`                                                        | If `true`, disables writing to the cookie.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `maxAge`      | `number`               | `undefined`                                                    | Max age in seconds for the cookie, i.e. the value for the [`Max-Age` `Set-Cookie` attribute](https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.2). The given number will be converted to an integer by rounding down. By default, no maximum age is set.                                                                                                                                                                                                                                                                                                                                                                                   |
+| `expires`     | `Date`                 | `undefined`                                                    | Expiration date for the cookie. By default, no expiration is set. Most clients will consider this a "non-persistent cookie" and will delete it on a condition like exiting a web browser application. <br/> **Note:** The [cookie storage model specification](https://datatracker.ietf.org/doc/html/rfc6265#section-5.3) states that if both `expires` and `maxAge` is set, then `maxAge` takes precedence, but not all clients may obey this, so if both are set, they should point to the same date and time! <br/>If neither of `expires` and `maxAge` is set, the cookie will be session-only and removed when the user closes their browser. |
+| `httpOnly`    | `boolean`              | `false`                                                        | Sets the HttpOnly attribute. <br/> **Note:** Be careful when setting this to `true`, as compliant clients will not allow client-side JavaScript to see the cookie in `document.cookie`.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `secure`      | `boolean`              | `false`                                                        | Sets the [`Secure` `Set-Cookie` attribute](https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.5). <br/>**Note:** Be careful when setting this to `true`, as compliant clients will not send the cookie back to the server in the future if the browser does not have an HTTPS connection. This can lead to hydration errors.                                                                                                                                                                                                                                                                                                                |
+| `partitioned` | `boolean`              | `false`                                                        | Sets the [`Partitioned` `Set-Cookie` attribute](https://datatracker.ietf.org/doc/html/draft-cutler-httpbis-partitioned-cookies#section-2.1). <br/>**Note:** This is an attribute that has not yet been fully standardized, and may change in the future. <br/>This also means many clients may ignore this attribute until they understand it.<br/>More information can be found in the [proposal](https://github.com/privacycg/CHIPS).                                                                                                                                                                                                            |
+| `domain`      | `string`               | `undefined`                                                    | Sets the [`Domain` `Set-Cookie` attribute](https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.3). By default, no domain is set, and most clients will consider applying the cookie only to the current domain.                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `path`        | `string`               | `'/'`                                                          | Sets the [`Path` `Set-Cookie` attribute](https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.4). By default, the path is considered the ["default path"](https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.4).                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `sameSite`    | `boolean \| string`    | `undefined`                                                    | Sets the [`SameSite` `Set-Cookie` attribute](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7). <br/>- `true` will set the `SameSite` attribute to `Strict` for strict same-site enforcement.<br/>- `false` will not set the `SameSite` attribute.<br/>- `'lax'` will set the `SameSite` attribute to `Lax` for lax same-site enforcement.<br/>- `'none'` will set the `SameSite` attribute to `None` for an explicit cross-site cookie.<br/>- `'strict'` will set the `SameSite` attribute to `Strict` for strict same-site enforcement.                                                                    |
+
+## Return Values
+
+Returns a Vue `Ref<T>` representing the cookie value. Updating the ref will update the cookie (unless `readonly` is set). The ref is SSR-friendly and will work on both client and server.
+
+## Examples
+
+### Basic Usage
+
+The example below creates a cookie called `counter`. If the cookie doesn't exist, it is initially set to a random value. Whenever we update the `counter` variable, the cookie will be updated accordingly.
+
+```vue [app.vue]
+<script setup lang="ts">
+const counter = useCookie('counter')
+
+counter.value ||= Math.round(Math.random() * 1000)
+</script>
+
+<template>
+  <div>
+    <h1>Counter: {{ counter || '-' }}</h1>
+    <button @click="counter = null">
+      reset
+    </button>
+    <button @click="counter--">
+      -
+    </button>
+    <button @click="counter++">
+      +
+    </button>
+  </div>
+</template>
+```
+
+### Readonly Cookies
+
+```vue
+<script setup lang="ts">
+const user = useCookie(
+  'userInfo',
+  {
+    default: () => ({ score: -1 }),
+    watch: false,
+  },
+)
+
+if (user.value) {
+  // the actual `userInfo` cookie will not be updated
+  user.value.score++
+}
+</script>
+
+<template>
+  <div>User score: {{ user?.score }}</div>
+</template>
+```
+
+### Writable Cookies
+
+```vue
+<script setup lang="ts">
+const list = useCookie(
+  'list',
+  {
+    default: () => [],
+    watch: 'shallow',
+  },
+)
+
+function add () {
+  list.value?.push(Math.round(Math.random() * 1000))
+  // list cookie won't be updated with this change
+}
+
+function save () {
+  // the actual `list` cookie will be updated
+  list.value &&= [...list.value]
+}
+</script>
+
+<template>
+  <div>
+    <h1>List</h1>
+    <pre>{{ list }}</pre>
+    <button @click="add">
+      Add
+    </button>
+    <button @click="save">
+      Save
+    </button>
+  </div>
+</template>
+```
+
+### Cookies in API Routes
+
+You can use `getCookie` and `setCookie` from [`h3`](https://github.com/h3js/h3) package to set cookies in server API routes.
+
+```ts [server/api/counter.ts]
+export default defineEventHandler((event) => {
+  // Read counter cookie
+  let counter = getCookie(event, 'counter') || 0
+
+  // Increase counter cookie by 1
+  setCookie(event, 'counter', ++counter)
+
+  // Send JSON response
+  return { counter }
+})
+```
+
+:link-example{to="/docs/3.x/examples/advanced/use-cookie"}

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

@@ -22,8 +22,8 @@ You can use this composable in your components, pages, or plugins to access or r
 
 ```ts
 interface NuxtError<DataT = unknown> {
-  statusCode: number
-  statusMessage: string
+  status: number
+  statusText: string
   message: string
   data?: DataT
   error?: true
@@ -52,4 +52,4 @@ if (error.value) {
 </script>
 ```
 
-:read-more{to="/docs/getting-started/error-handling"}
+:read-more{to="/docs/3.x/getting-started/error-handling"}

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/3.x/guide/recipes/custom-usefetch#custom-usefetch) for more information on how to make a custom async data fetcher.
+::warning{to="/docs/3.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
@@ -96,11 +96,11 @@ If you encounter the `data` variable destructured from a `useFetch` returns a st
 
 :video-accordion{title="Watch the video from Alexander Lichter to avoid using useFetch the wrong way" videoId="njsGVmcWviY"}
 
-:read-more{to="/docs/getting-started/data-fetching"}
+:read-more{to="/docs/3.x/getting-started/data-fetching"}
 
 ### Reactive Fetch Options
 
-Fetch options can be provided as reactive, supporting `computed`, `ref` and [computed getters](https://vuejs.org/guide/essentials/computed.html). When a reactive fetch option is updated it will trigger a refetch using the updated resolved reactive value.
+Fetch options can be provided as reactive, supporting `computed`, `ref` and [computed getters](https://vuejs.org/guide/essentials/computed). When a reactive fetch option is updated it will trigger a refetch using the updated resolved reactive value.
 
 ```ts
 const searchQuery = ref('initial')
@@ -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/3.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` | `true` | Return data in a deep ref object. Set to `false` to return data in a shallow ref object, which can improve performance if your data does not need to be deeply reactive. |
-| `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/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/3.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 `null`, 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
 
@@ -244,6 +244,6 @@ If you have not fetched data on the server (for example, with `server: false`),
 
 ### Examples
 
-:link-example{to="/docs/examples/advanced/use-custom-fetch-composable"}
+:link-example{to="/docs/3.x/examples/advanced/use-custom-fetch-composable"}
 
-:link-example{to="/docs/examples/features/data-fetching"}
+:link-example{to="/docs/3.x/examples/features/data-fetching"}

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

@@ -50,7 +50,7 @@ This composable does not return any value.
 
 ## Example
 
-```vue [app/pages/user-profile.vue]
+```vue [pages/user-profile.vue]
 <script setup lang="ts">
 // User-generated content that might contain malicious code
 const userBio = ref('<script>alert("xss")<' + '/script>')

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

@@ -12,7 +12,7 @@ links:
 
 The `useHead` composable allows you to manage your head tags in a programmatic and reactive way, powered by [Unhead](https://unhead.unjs.io). It lets you customize the meta tags, links, scripts, and other elements in the `<head>` section of your HTML document.
 
-```vue [app/app.vue]
+```vue [app.vue]
 <script setup lang="ts">
 useHead({
   title: 'My App',
@@ -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.
@@ -81,7 +96,7 @@ This composable does not return any value. It registers the head metadata with U
 
 ### Basic Meta Tags
 
-```vue [app/pages/about.vue]
+```vue [pages/about.vue]
 <script setup lang="ts">
 useHead({
   title: 'About Us',
@@ -96,7 +111,7 @@ useHead({
 
 ### Reactive Meta Tags
 
-```vue [app/pages/profile.vue]
+```vue [pages/profile.vue]
 <script setup lang="ts">
 const profile = ref({ name: 'John Doe' })
 
@@ -114,7 +129,7 @@ useHead({
 
 ### Using a Function for Full Reactivity
 
-```vue [app/pages/dynamic.vue]
+```vue [pages/dynamic.vue]
 <script setup lang="ts">
 const count = ref(0)
 
@@ -129,7 +144,7 @@ useHead(() => ({
 
 ### Adding External Scripts and Styles
 
-```vue [app/pages/external.vue]
+```vue [pages/external.vue]
 <script setup lang="ts">
 useHead({
   link: [
@@ -150,7 +165,7 @@ useHead({
 
 ### Body and HTML Attributes
 
-```vue [app/pages/themed.vue]
+```vue [pages/themed.vue]
 <script setup lang="ts">
 const isDark = ref(true)
 

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

@@ -16,7 +16,7 @@ By default, [`useAsyncData`](/docs/3.x/api/composables/use-async-data) blocks na
 
 ## Usage
 
-```vue [app/pages/index.vue]
+```vue [pages/index.vue]
 <script setup lang="ts">
 const { status, data: posts } = await useLazyAsyncData('posts', () => $fetch('/api/posts'))
 </script>

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

@@ -14,7 +14,7 @@ links:
 
 By default, [`useFetch`](/docs/3.x/api/composables/use-fetch) blocks navigation until its async handler is resolved. `useLazyFetch` allows navigation to proceed immediately, with data being fetched in the background.
 
-```vue [app/pages/index.vue]
+```vue [pages/index.vue]
 <script setup lang="ts">
 const { status, data: posts } = await useLazyFetch('/api/posts')
 </script>
@@ -69,14 +69,14 @@ export function useLazyFetch<DataT, ErrorT> (
 
 Returns the same `AsyncData` object as [`useFetch`](/docs/3.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/3.x/api/composables/use-fetch#return-values"}
 

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

@@ -16,7 +16,7 @@ const nuxtApp = useNuxtApp()
 </script>
 ```
 
-If runtime context is unavailable in your scope, `useNuxtApp` will throw an exception when called. You can use [`tryUseNuxtApp`](#tryusenuxtapp) instead for composables that do not require `nuxtApp`, or to simply check if context is available or not without an exception.
+If runtime context is unavailable in your scope, `useNuxtApp` will throw an exception when called. You can use [`tryUseNuxtApp`](/docs/3.x/api/composables/use-nuxt-app#tryusenuxtapp) instead for composables that do not require `nuxtApp`, or to simply check if context is available or not without an exception.
 
 <!--
 note
@@ -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/3.x/guide/directory-structure/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/3.x/directory-structure/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/3.x/guide/directory-structure/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/3.x/directory-structure/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.
 
@@ -80,12 +80,12 @@ await nuxtApp.callHook('my-plugin:init')
 
 ### `vueApp`
 
-`vueApp` is the global Vue.js [application instance](https://vuejs.org/api/application.html#application-api) that you can access through `nuxtApp`.
+`vueApp` is the global Vue.js [application instance](https://vuejs.org/api/application#application-api) that you can access through `nuxtApp`.
 
 Some useful methods:
-- [`component()`](https://vuejs.org/api/application.html#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.html#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/3.x/guide/directory-structure/plugins#vue-directives).
-- [`use()`](https://vuejs.org/api/application.html#app-use) - Installs a **[Vue.js Plugin](https://vuejs.org/guide/reusability/plugins.html)** [(example)](/docs/3.x/guide/directory-structure/plugins#vue-plugins).
+- [`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/3.x/directory-structure/plugins#vue-directives).
+- [`use()`](https://vuejs.org/api/application#app-use) - Installs a **[Vue.js Plugin](https://vuejs.org/guide/reusability/plugins)** [(example)](/docs/3.x/directory-structure/plugins#vue-plugins).
 
 :read-more{icon="i-simple-icons-vuedotjs" to="https://vuejs.org/api/application.html#application-api"}
 
@@ -120,7 +120,7 @@ Nuxt exposes the following properties through `ssrContext`:
 
   After fetching the value of `count` using [`useAsyncData`](/docs/3.x/api/composables/use-async-data) in the example above, if you access `payload.data`, you will see `{ count: 1 }` recorded there.
 
-  When accessing the same `payload.data` from [`ssrcontext`](#ssrcontext), you can access the same value on the server side as well.
+  When accessing the same `payload.data` from [`ssrcontext`](/docs/3.x/api/composables/use-nuxt-app#ssrcontext), you can access the same value on the server side as well.
 
 - `state` (object) - When you use [`useState`](/docs/3.x/api/composables/use-state) composable in Nuxt to set shared state, this state data is accessed through `payload.state.[name-of-your-state]`.
 
@@ -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"}
@@ -268,7 +270,7 @@ Using a new experimental feature, it is possible to enable native async context
 Native async context support works currently in Bun and Node.
 ::
 
-:read-more{to="/docs/guide/going-further/experimental-features#asynccontext"}
+:read-more{to="/docs/3.x/guide/going-further/experimental-features#asynccontext"}
 
 ## tryUseNuxtApp
 

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/3.x/guide/directory-structure/middleware) to set a response header for all pages.
+We can use `useResponseHeader` for example in Nuxt [middleware](/docs/3.x/directory-structure/middleware) to set a response header for all pages.
 
 ```ts [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/3.x/guide/directory-structure/app/middleware"}
+::read-more{to="/docs/3.x/directory-structure/middleware"}
 Read more about accessing the route in the middleware section.
 ::
 
@@ -84,4 +84,4 @@ Read more about accessing the route in the middleware section.
 
 Browsers don't send [URL fragments](https://url.spec.whatwg.org/#concept-url-fragment) (for example `#foo`) when making requests. So using `route.fullPath` to affect the template can trigger hydration issues because this will include the fragment on client but not the server.
 
-:read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/type-aliases/RouteLocationNormalizedLoaded.html"}
+:read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/type-aliases/routelocationnormalizedloaded"}