@nuxt/docs 3.17.4 → 3.17.6

package/3.api/1.components/9.nuxt-img.md

@@ -21,7 +21,7 @@ links:
 In order to use `<NuxtImg>` you should install and enable the Nuxt Image module:
 
 ```bash [Terminal]
-npx nuxi@latest module add image
+npx nuxt module add image
 ```
 
 ## Usage

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

@@ -12,23 +12,33 @@ links:
 This composable is available in Nuxt v3.12+.
 ::
 
-`onPrehydrate` is a composable lifecycle hook that allows you to run a callback on the client immediately before
-Nuxt hydrates the page.
-
+`onPrehydrate` is a composable lifecycle hook that allows you to run a callback on the client immediately before Nuxt hydrates the page.
 ::note
 This is an advanced utility and should be used with care. For example, [`nuxt-time`](https://github.com/danielroe/nuxt-time/pull/251) and [`@nuxtjs/color-mode`](https://github.com/nuxt-modules/color-mode/blob/main/src/script.js) manipulate the DOM to avoid hydration mismatches.
 ::
 
 ## Usage
 
-`onPrehydrate` can be called directly in the setup function of a Vue component (for example, in `<script setup>`), or in a plugin.
-It will only have an effect when it is called on the server, and it will not be included in your client build.
+Call `onPrehydrate` in the setup function of a Vue component (e.g., in `<script setup>`) or in a plugin. It only has an effect when called on the server and will not be included in your client build.
+
+## Type
+
+```ts [Signature]
+export function onPrehydrate(callback: (el: HTMLElement) => void): void
+export function onPrehydrate(callback: string | ((el: HTMLElement) => void), key?: string): undefined | string
+```
 
 ## Parameters
 
-- `callback`: A function that will be stringified and inlined in the HTML. It should not have any external
-dependencies (such as auto-imports) or refer to variables defined outside the callback. The callback will run
-before Nuxt runtime initializes so it should not rely on the Nuxt or Vue context.
+| Parameter | Type | Required | Description |
+| ---- | --- | --- | --- |
+| `callback` | `((el: HTMLElement) => void) \| string` | Yes | A function (or stringified function) to run before Nuxt hydrates. It will be stringified and inlined in the HTML. Should not have external dependencies or reference variables outside the callback. Runs before Nuxt runtime initializes, so it should not rely on Nuxt or Vue context. |
+| `key` | `string` | No | (Advanced) A unique key to identify the prehydrate script, useful for advanced scenarios like multiple root nodes. |
+
+## Return Values
+
+- Returns `undefined` when called with only a callback function.
+- Returns a string (the prehydrate id) when called with a callback and a key, which can be used to set or access the `data-prehydrate-id` attribute for advanced use cases.
 
 ## Example
 
@@ -36,19 +46,18 @@ before Nuxt runtime initializes so it should not rely on the Nuxt or Vue context
 <script setup lang="ts">
 declare const window: Window
 // ---cut---
-// onPrehydrate is guaranteed to run before Nuxt hydrates
+// Run code before Nuxt hydrates
 onPrehydrate(() => {
   console.log(window)
 })
 
-// As long as it only has one root node, you can access the element
+// Access the root element
 onPrehydrate((el) => {
   console.log(el.outerHTML)
   // <div data-v-inspector="app.vue:15:3" data-prehydrate-id=":b3qlvSiBeH:"> Hi there </div>
 })
 
-// For _very_ advanced use cases (such as not having a single root node) you
-// can access/set `data-prehydrate-id` yourself
+// Advanced: access/set `data-prehydrate-id` yourself
 const prehydrateId = onPrehydrate((el) => {})
 </script>
 

package/3.api/2.composables/use-async-data.md

@@ -154,7 +154,7 @@ const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { imm
   - `pending`: the request is in progress
   - `success`: the request has completed successfully
   - `error`: the request has failed
-- `clear`: a function which will set `data` to `undefined`, set `error` to `null`, set `status` to `'idle'`, and mark any currently pending requests as cancelled.
+- `clear`: a function that can be used to set `data` to `undefined` (or the value of `options.default()` if provided), set `error` to `null`, set `status` to `idle`, and mark any currently pending requests as cancelled.
 
 By default, Nuxt waits until a `refresh` is finished before it can be executed again.
 

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

@@ -8,7 +8,9 @@ links:
     size: xs
 ---
 
-Within your pages, components and plugins you can use `useCookie`, an SSR-friendly composable to read and write cookies.
+## 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)
@@ -19,144 +21,83 @@ const cookie = useCookie(name, options)
 ::
 
 ::tip
-`useCookie` ref will automatically serialize and deserialize cookie value to JSON.
+The returned ref will automatically serialize and deserialize cookie values to JSON.
 ::
 
-## Example
+## Type
 
-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.
+```ts [Signature]
+import type { Ref } from 'vue'
+import type { CookieParseOptions, CookieSerializeOptions } from 'cookie-es'
 
-```vue [app.vue]
-<script setup lang="ts">
-const counter = useCookie('counter')
+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
+}
 
-counter.value = counter.value || Math.round(Math.random() * 1000)
-</script>
+export interface CookieRef<T> extends Ref<T> {}
 
-<template>
-  <div>
-    <h1>Counter: {{ counter || '-' }}</h1>
-    <button @click="counter = null">reset</button>
-    <button @click="counter--">-</button>
-    <button @click="counter++">+</button>
-  </div>
-</template>
+export function useCookie<T = string | null | undefined>(
+  name: string,
+  options?: CookieOptions<T>
+): CookieRef<T>
 ```
 
-:link-example{to="/docs/examples/advanced/use-cookie"}
-
-::note
-Refresh `useCookie` values manually when a cookie has changed with [`refreshCookie`](/docs/api/utils/refresh-cookie).
-::
+## Parameters
 
-## Options
+`name`: The name of the cookie.
 
-Cookie composable accepts several options which let you modify the behavior of cookies.
+`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.
 
-### `maxAge` / `expires`
+| 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/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://tools.ietf.org/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://tools.ietf.org/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://tools.ietf.org/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://tools.ietf.org/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://tools.ietf.org/html/rfc6265#section-5.2.4). By default, the path is considered the ["default path"](https://tools.ietf.org/html/rfc6265#section-5.1.4). |
+| `sameSite` | `boolean \| string` | `undefined` | Sets the [`SameSite` `Set-Cookie` attribute](https://tools.ietf.org/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. |
 
-Use these options to set the expiration of the cookie.
+## Return Values
 
-`maxAge`: Specifies the `number` (in seconds) to be the value for the [`Max-Age` `Set-Cookie` attribute](https://tools.ietf.org/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.
+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.
 
-`expires`: Specifies the `Date` object to be the value for the [`Expires` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.1).
-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.
+## Examples
 
-::note
-The [cookie storage model specification](https://tools.ietf.org/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!
-::
-
-::note
-If neither of `expires` and `maxAge` is set, the cookie will be session-only and removed when the user closes their browser.
-::
-
-### `httpOnly`
-
-Specifies the `boolean` value for the [`HttpOnly` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.6). When truthy, the `HttpOnly` attribute is set; otherwise it is not. By default, the `HttpOnly` attribute is not set.
-
-::warning
-Be careful when setting this to `true`, as compliant clients will not allow client-side JavaScript to see the cookie in `document.cookie`.
-::
-
-### `secure`
-
-Specifies the `boolean` value for the [`Secure` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.5). When truthy, the `Secure` attribute is set; otherwise it is not. By default, the `Secure` attribute is not set.
-
-::warning
-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`
-
-Specifies the `boolean` value for the [`Partitioned` `Set-Cookie`](https://datatracker.ietf.org/doc/html/draft-cutler-httpbis-partitioned-cookies#section-2.1) attribute. When truthy, the `Partitioned` attribute is set, otherwise it is not. By default, the `Partitioned` attribute is not set.
-
-::note
-This is an attribute that has not yet been fully standardized, and may change in the future.
-This also means many clients may ignore this attribute until they understand it.
-
-More information can be found in the [proposal](https://github.com/privacycg/CHIPS).
-::
+### Basic Usage
 
-### `domain`
-
-Specifies the value for the [`Domain` `Set-Cookie` attribute](https://tools.ietf.org/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`
-
-Specifies the value for the [`Path` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.4). By default, the path is considered the ["default path"](https://tools.ietf.org/html/rfc6265#section-5.1.4).
-
-### `sameSite`
-
-Specifies the `boolean` or `string` value for the [`SameSite` `Set-Cookie` attribute](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7).
-
-- `true` will set the `SameSite` attribute to `Strict` for strict same-site enforcement.
-- `false` will not set the `SameSite` attribute.
-- `'lax'` will set the `SameSite` attribute to `Lax` for lax same-site enforcement.
-- `'none'` will set the `SameSite` attribute to `None` for an explicit cross-site cookie.
-- `'strict'` will set the `SameSite` attribute to `Strict` for strict same-site enforcement.
-
-More information about the different enforcement levels can be found in [the specification](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7).
-
-### `encode`
-
-Specifies a function that will be used to encode a cookie's 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.
-
-The default encoder is the `JSON.stringify` + `encodeURIComponent`.
-
-### `decode`
-
-Specifies a function that will be used to decode a cookie's 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.
-
-The default decoder is `decodeURIComponent` + [destr](https://github.com/unjs/destr).
-
-::note
-If an error is thrown from this function, the original, non-decoded cookie value will be returned as the cookie's value.
-::
-
-### `default`
-
-Specifies a function that returns the cookie's default value. The function can also return a `Ref`.
-
-### `readonly`
-
-Allows _accessing_ a cookie value without the ability to set it.
-
-### `watch`
+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.
 
-Specifies the `boolean` or `string` value for [watch](https://vuejs.org/api/reactivity-core.html#watch) cookie ref data.
+```vue [app.vue]
+<script setup lang="ts">
+const counter = useCookie('counter')
 
-- `true` - Will watch cookie ref data changes and its nested properties (default).
-- `shallow` - Will watch cookie ref data changes for only top level properties
-- `false` - Will not watch cookie ref data changes.
+counter.value = counter.value || Math.round(Math.random() * 1000)
+</script>
 
-::note
-Refresh `useCookie` values manually when a cookie has changed with [`refreshCookie`](/docs/api/utils/refresh-cookie).
-::
+<template>
+  <div>
+    <h1>Counter: {{ counter || '-' }}</h1>
+    <button @click="counter = null">reset</button>
+    <button @click="counter--">-</button>
+    <button @click="counter++">+</button>
+  </div>
+</template>
+```
 
-**Example 1:**
+### Readonly Cookies
 
 ```vue
 <script setup lang="ts">
@@ -168,8 +109,9 @@ const user = useCookie(
   }
 )
 
-if (user.value && user.value !== null) {
-  user.value.score++; // userInfo cookie not update with this change
+if (user.value) {
+  // the actual `userInfo` cookie will not be updated
+  user.value.score++
 }
 </script>
 
@@ -178,7 +120,7 @@ if (user.value && user.value !== null) {
 </template>
 ```
 
-**Example 2:**
+### Writable Cookies
 
 ```vue
 <script setup lang="ts">
@@ -192,13 +134,13 @@ const list = useCookie(
 
 function add() {
   list.value?.push(Math.round(Math.random() * 1000))
-  // list cookie not update with this change
+  // list cookie won't be updated with this change
 }
 
 function save() {
-  if (list.value && list.value !== null) {
+  if (list.value) {
+    // the actual `list` cookie will be updated
     list.value = [...list.value]
-    // list cookie update with this change
   }
 }
 </script>
@@ -213,9 +155,9 @@ function save() {
 </template>
 ```
 
-## Cookies in API Routes
+### Cookies in API Routes
 
-You can use `getCookie` and `setCookie` from [`h3`](https://github.com/unjs/h3) package to set cookies in server 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 => {

package/3.api/2.composables/use-error.md

@@ -8,25 +8,48 @@ links:
     size: xs
 ---
 
-The composable returns the global Nuxt error that is being handled and it is available on both client and server.
+## Usage
+
+The `useError` composable returns the global Nuxt error that is being handled and is available on both client and server. It provides a reactive, SSR-friendly error state across your app.
 
 ```ts
 const error = useError()
 ```
 
-`useError` sets an error in the state and creates a reactive as well as SSR-friendly global Nuxt error across components.
+You can use this composable in your components, pages, or plugins to access or react to the current Nuxt error.
 
-Nuxt errors have the following properties:
+## Type
 
 ```ts
-interface {
-  //  HTTP response status code
+interface NuxtError<DataT = unknown> {
   statusCode: number
-  // HTTP response status message
   statusMessage: string
-  // Error message
   message: string
+  data?: DataT
+  error?: true
+}
+
+export const useError: () => Ref<NuxtError | undefined>
+```
+
+## Parameters
+
+This composable does not take any parameters.
+
+## Return Values
+
+Returns a `Ref` containing the current Nuxt error (or `undefined` if there is no error). The error object is reactive and will update automatically when the error state changes.
+
+## Example
+
+```ts
+<script setup lang="ts">
+const error = useError()
+
+if (error.value) {
+  console.error('Nuxt error:', error.value)
 }
+</script>
 ```
 
 :read-more{to="/docs/getting-started/error-handling"}

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

@@ -92,81 +92,8 @@ 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"}
 
-:link-example{to="/docs/examples/advanced/use-custom-fetch-composable"}
-
 :read-more{to="/docs/getting-started/data-fetching"}
 
-:link-example{to="/docs/examples/features/data-fetching"}
-
-## Params
-
-- `URL`: The URL to fetch.
-- `Options` (extends [unjs/ofetch](https://github.com/unjs/ofetch) options & [AsyncDataOptions](/docs/api/composables/use-async-data#params)):
-  - `method`: Request method.
-  - `query`: Adds query search params to URL using [ufo](https://github.com/unjs/ufo)
-  - `params`: Alias for `query`
-  - `body`: Request body - automatically stringified (if an object is passed).
-  - `headers`: Request headers.
-  - `baseURL`: Base URL for the request.
-  - `timeout`: Milliseconds to automatically abort request
-  - `cache`: Handles cache control according to [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/fetch#cache)
-    - You can pass boolean to disable the cache or you can pass one of the following values: `default`, `no-store`, `reload`, `no-cache`, `force-cache`, and `only-if-cached`.
-
-::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.
-::
-
-- `Options` (from [`useAsyncData`](/docs/api/composables/use-async-data)):
-  - `key`: a unique key to ensure that data fetching can be properly de-duplicated across requests, if not provided, it will be automatically generated based on URL and fetch options
-  - `server`: whether to fetch the data on the server (defaults to `true`)
-  - `lazy`: whether to resolve the async function after loading the route, instead of blocking client-side navigation (defaults to `false`)
-  - `immediate`: when set to `false`, will prevent the request from firing immediately. (defaults to `true`)
-  - `default`: a factory function to set the default value of the `data`, before the async function resolves - useful with the `lazy: true` or `immediate: false` option
-  - `transform`: a function that can be used to alter `handler` function result after resolving
-  - `getCachedData`: Provide a function which returns cached data. A `null` or `undefined` return value will trigger a fetch. By default, this is:
-    ```ts
-    const getDefaultCachedData = (key, nuxtApp, ctx) => nuxtApp.isHydrating 
-      ? nuxtApp.payload.data[key] 
-      : nuxtApp.static.data[key]
-    ```
-    Which only caches data when `experimental.payloadExtraction` of `nuxt.config` is enabled.
-  - `pick`: only pick specified keys in this array from the `handler` function result
-  - `watch`: watch an array of reactive sources and auto-refresh the fetch result when they change. Fetch options and URL are watched by default. You can completely ignore reactive sources by using `watch: false`. Together with `immediate: false`, this allows for a fully-manual `useFetch`. (You can [see an example here](/docs/getting-started/data-fetching#watch) of using `watch`.)
-  - `deep`: return data in a deep ref object (it is `true` by default). It can be 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`: avoid fetching same key more than once at a time (defaults to `cancel`). Possible options:
-    - `cancel` - cancels existing requests when a new one is made
-    - `defer` - does not make new requests at all if there is a pending request
-
-::note
-If you provide a function or ref as the `url` parameter, or if you provide functions as arguments to the `options` parameter, then the `useFetch` call will not match other `useFetch` calls elsewhere in your codebase, even if the options seem to be identical. If you wish to force a match, you may provide your own key in `options`.
-::
-
-::note
-If you use `useFetch` to call an (external) HTTPS URL with a self-signed certificate in development, you will need to set `NODE_TLS_REJECT_UNAUTHORIZED=0` in your environment.
-::
-
-:video-accordion{title="Watch a video from Alexander Lichter about client-side caching with getCachedData" videoId="aQPR0xn-MMk"}
-
-## Return Values
-
-- `data`: the result of the asynchronous function that is passed in.
-- `refresh`/`execute`: a function that can be used to refresh the data returned by the `handler` function.
-- `error`: an error object if the data fetching failed.
-- `status`: a string indicating the status of the data request:
-  - `idle`: when the request has not started, such as:
-    - when `execute` has not yet been called and `{ immediate: false }` is set
-    - when rendering HTML on the server and `{ server: false }` is set
-  - `pending`: the request is in progress
-  - `success`: the request has completed successfully
-  - `error`: the request has failed
-- `clear`: a function which will set `data` to `undefined`, set `error` to `null`, set `status` to `'idle'`, and mark any currently pending requests as cancelled.
-
-By default, Nuxt waits until a `refresh` is finished before it can be executed again.
-
-::note
-If you have not fetched data on the server (for example, with `server: false`), then the data _will not_ be fetched until hydration completes. This means even if you await `useFetch` on client-side, `data` will remain null within `<script setup>`.
-::
-
 ## Type
 
 ```ts [Signature]
@@ -215,3 +142,73 @@ interface AsyncDataExecuteOptions {
 
 type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'
 ```
+
+## Parameters
+
+- `URL` (`string | Request | Ref<string | Request> | () => string | Request`): The URL or request to fetch. Can be a string, a Request object, a Vue ref, or a function returning a string/Request. Supports reactivity for dynamic endpoints.
+
+- `options` (object): Configuration for the fetch request. Extends [unjs/ofetch](https://github.com/unjs/ofetch) options and [`AsyncDataOptions`](/docs/api/composables/use-async-data#params). All options can be a static value, a `ref`, or a computed value.
+
+| Option | Type | Default | Description |
+| ---| --- | --- | --- |
+| `key` | `string` | auto-gen | Unique key for de-duplication. If not provided, generated from URL and options. |
+| `method` | `string` | `'GET'` | HTTP request method. |
+| `query` | `object` | - | Query/search params to append to the URL. Alias: `params`. Supports refs/computed. |
+| `params` | `object` | - | Alias for `query`. |
+| `body` | `RequestInit['body'] \| Record<string, any>` | - | Request body. Objects are automatically stringified. Supports refs/computed. |
+| `headers` | `Record<string, string> \| [key, value][] \| Headers` | - | Request headers. |
+| `baseURL` | `string` | - | Base URL for the request. |
+| `timeout` | `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. |
+| `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` | `WatchSource[] \| 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 $fetch` | - | Custom $fetch implementation. |
+
+::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.
+::
+
+**getCachedData default:**
+
+```ts
+const getDefaultCachedData = (key, nuxtApp, ctx) => nuxtApp.isHydrating 
+ ? nuxtApp.payload.data[key] 
+ : nuxtApp.static.data[key]
+```
+This only caches data when `experimental.payloadExtraction` in `nuxt.config` is enabled.
+
+## Return Values
+
+| Name | Type | Description |
+| --- | --- |--- |
+| `data` | `Ref<DataT \| null>` | 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 \| null>` | 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. |
+
+### Status values
+
+- `idle`: Request has not started (e.g. `{ immediate: false }` or `{ server: false }` on server render)
+- `pending`: Request is in progress
+- `success`: Request completed successfully
+- `error`: Request failed
+
+::note
+If you have not fetched data on the server (for example, with `server: false`), then the data _will not_ be fetched until hydration completes. This means even if you await `useFetch` on client-side, `data` will remain null within `<script setup>`.
+::
+
+### Examples
+
+:link-example{to="/docs/examples/advanced/use-custom-fetch-composable"}
+
+:link-example{to="/docs/examples/features/data-fetching"}

package/3.api/2.composables/use-nuxt-app.md

@@ -95,7 +95,7 @@ Some useful methods:
 
 Nuxt exposes the following properties through `ssrContext`:
 - `url` (string) -  Current request url.
-- `event` ([unjs/h3](https://github.com/unjs/h3) request event) - Access the request & response of the current route.
+- `event` ([h3js/h3](https://github.com/h3js/h3) request event) - Access the request & response of the current route.
 - `payload` (object) - NuxtApp payload object.
 
 ### `payload`

package/3.api/2.composables/use-preview-mode.md

@@ -103,8 +103,8 @@ const { data } = await useFetch('/api/preview', {
 Now you can generate your site and serve it:
 
 ```bash [Terminal]
-npx nuxi generate
-npx nuxi preview
+npx nuxt generate
+npx nuxt preview
 ```
 
 Then you can see your preview page by adding the query param `preview` to the end of the page you want to see once:
@@ -114,5 +114,5 @@ Then you can see your preview page by adding the query param `preview` to the en
 ```
 
 ::note
-`usePreviewMode` should be tested locally with `nuxi generate` and then `nuxi preview` rather than `nuxi dev`. (The [preview command](/docs/api/commands/preview) is not related to preview mode.)
+`usePreviewMode` should be tested locally with `nuxt generate` and then `nuxt preview` rather than `nuxt dev`. (The [preview command](/docs/api/commands/preview) is not related to preview mode.)
 ::