@nuxt/docs-nightly 4.0.0-29178461.f99b7b01 → 4.0.0-29179457.2dafcc72

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

@@ -230,7 +230,7 @@ Read more about `useAsyncData`.
 
 - `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.
-- `clear`: a function that can be used to 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 `undefined`, set `status` to `idle`, and mark any currently pending requests as cancelled.
 - `error`: an error object if the data fetching failed.
 - `status`: a string indicating the status of the data request (`"idle"`, `"pending"`, `"success"`, `"error"`).
 

package/1.getting-started/13.server.md

@@ -18,7 +18,7 @@ Using Nitro gives Nuxt superpowers:
 - Universal deployment on any provider (many zero-config)
 - Hybrid rendering
 
-Nitro is internally using [h3](https://github.com/unjs/h3), a minimal H(TTP) framework built for high performance and portability.
+Nitro is internally using [h3](https://github.com/h3js/h3), a minimal H(TTP) framework built for high performance and portability.
 
 :video-accordion{title="Watch a video from Alexander Lichter to understand the responsibilities of Nuxt and Nitro in your application" videoId="DkvgJa-X31k"}
 

package/2.guide/1.concepts/4.server-engine.md

@@ -16,7 +16,7 @@ It is shipped with many features:
 
 ## API Layer
 
-Server [API endpoints](/docs/guide/directory-structure/server#api-routes) and [Middleware](/docs/guide/directory-structure/server#server-middleware) are added by Nitro that internally uses [h3](https://github.com/unjs/h3).
+Server [API endpoints](/docs/guide/directory-structure/server#api-routes) and [Middleware](/docs/guide/directory-structure/server#server-middleware) are added by Nitro that internally uses [h3](https://github.com/h3js/h3).
 
 Key features include:
 
@@ -24,7 +24,7 @@ Key features include:
 - Handlers can return promises, which will be awaited (`res.end()` and `next()` are also supported)
 - Helper functions for body parsing, cookie handling, redirects, headers and more
 
-Check out [the h3 docs](https://github.com/unjs/h3) for more information.
+Check out [the h3 docs](https://github.com/h3js/h3) for more information.
 
 ::read-more{to="/docs/guide/directory-structure/server#server-routes"}
 Learn more about the API layer in the `server/` directory.

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

@@ -101,7 +101,7 @@ export default defineNitroPlugin((nitroApp) => {
 
 ## Server Utilities
 
-Server routes are powered by [unjs/h3](https://github.com/unjs/h3) which comes with a handy set of helpers.
+Server routes are powered by [h3js/h3](https://github.com/h3js/h3) which comes with a handy set of helpers.
 
 :read-more{to="https://www.jsdocs.io/package/h3#package-index-functions" title="Available H3 Request Helpers" target="_blank"}
 
@@ -448,7 +448,7 @@ export default fromNodeMiddleware((req, res) => {
 ```
 
 ::important
-Legacy support is possible using [unjs/h3](https://github.com/unjs/h3), but it is advised to avoid legacy handlers as much as you can.
+Legacy support is possible using [h3js/h3](https://github.com/h3js/h3), but it is advised to avoid legacy handlers as much as you can.
 ::
 
 ```ts [server/middleware/legacy.ts]

package/2.guide/3.going-further/3.modules.md

@@ -230,8 +230,6 @@ Learn more about asset injection in [the recipes section](#recipes).
 Published modules cannot leverage auto-imports for assets within their runtime directory. Instead, they have to import them explicitly from `#imports` or alike.
 :br :br
 Indeed, auto-imports are not enabled for files within `node_modules` (the location where a published module will eventually live) for performance reasons.
-:br :br
-If you are using the module starter, auto-imports will not be enabled in your playground either.
 ::
 
 ### Tooling

package/3.api/1.components/4.nuxt-link.md

@@ -51,6 +51,10 @@ In this example, we pass the `id` param to link to the route `~/pages/posts/[id]
 Check out the Pages panel in Nuxt DevTools to see the route name and the params it might take.
 ::
 
+::tip
+When you pass an object into the `to` prop, `<NuxtLink>` will inherit Vue Router’s handling of query parameters. Keys and values will be automatically encoded, so you don’t need to call `encodeURI` or `encodeURIComponent` manually.
+::
+
 ### Handling Static File and Cross-App Links
 
 By default, `<NuxtLink>` uses Vue Router's client side navigation for relative route. When linking to static files in the `/public` directory or to another application hosted on the same domain, it might result in unexpected 404 errors because they are not part of the client routes. In such cases, you can use the `external` prop with `<NuxtLink>` to bypass Vue Router's internal routing mechanism.

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 `undefined`, 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">
@@ -179,7 +120,7 @@ if (user.value) {
 </template>
 ```
 
-**Example 2:**
+### Writable Cookies
 
 ```vue
 <script setup lang="ts">
@@ -193,7 +134,7 @@ 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() {
@@ -214,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 `false` by default 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 `undefined`, 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/3.utils/define-nuxt-plugin.md

@@ -0,0 +1,102 @@
+---
+title: "defineNuxtPlugin"
+description: defineNuxtPlugin() is a helper function for creating Nuxt plugins.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/nuxt.ts
+    size: xs
+---
+
+`defineNuxtPlugin` is a helper function for creating Nuxt plugins with enhanced functionality and type safety. This utility normalizes different plugin formats into a consistent structure that works seamlessly within Nuxt's plugin system.
+
+```ts twoslash [plugins/hello.ts]
+export default defineNuxtPlugin((nuxtApp) => {
+  // Doing something with nuxtApp
+})
+```
+
+:read-more{to="/docs/guide/directory-structure/plugins#creating-plugins"}
+
+## Type
+
+```ts
+defineNuxtPlugin<T extends Record<string, unknown>>(plugin: Plugin<T> | ObjectPlugin<T>): Plugin<T> & ObjectPlugin<T>
+
+type Plugin<T> = (nuxt: [NuxtApp](/docs/guide/going-further/internals#the-nuxtapp-interface)) => Promise<void> | Promise<{ provide?: T }> | void | { provide?: T }
+
+interface ObjectPlugin<T> {
+  name?: string
+  enforce?: 'pre' | 'default' | 'post'
+  dependsOn?: string[]
+  order?: number
+  parallel?: boolean
+  setup?: Plugin<T>
+  hooks?: Partial<[RuntimeNuxtHooks](/docs/api/advanced/hooks#app-hooks-runtime)>
+  env?: {
+    islands?: boolean
+  }
+}
+```
+
+## Parameters
+
+**plugin**: A plugin can be defined in two ways:
+1. **Function Plugin**: A function that receives the [`NuxtApp`](/docs/guide/going-further/internals#the-nuxtapp-interface) instance and can return a promise with an potential object with a [`provide`](/docs/guide/directory-structure/plugins#providing-helpers) property if you want to provide a helper on [`NuxtApp`](/docs/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. |
+
+:video-accordion{title="Watch a video from Alexander Lichter about the Object Syntax for Nuxt plugins" videoId="2aXZyXB1QGQ"}
+
+## Examples
+
+### Basic Usage
+
+The example below demonstrates a simple plugin that adds global functionality:
+
+```ts twoslash [plugins/hello.ts]
+export default defineNuxtPlugin((nuxtApp) => {
+  // Add a global method
+  return {
+    provide: {
+      hello: (name: string) => `Hello ${name}!`
+    }
+  }
+})
+```
+
+### Object Syntax Plugin
+
+The example below shows the object syntax with advanced configuration:
+
+```ts twoslash [plugins/advanced.ts]
+export default defineNuxtPlugin({
+  name: 'my-plugin',
+  enforce: 'pre',
+  async setup (nuxtApp) {
+    // Plugin setup logic
+    const data = await $fetch('/api/config')
+    
+    return {
+      provide: {
+        config: data
+      }
+    }
+  },
+  hooks: {
+    'app:created'() {
+      console.log('App created!')
+    }
+  },
+})
+```

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

@@ -95,11 +95,11 @@ See [Nitro](https://nitro.build/guide/plugins#available-hooks) for all available
 Hook                   | Arguments             | Description                          | Types
 -----------------------|-----------------------|--------------------------------------|------------------
 `dev:ssr-logs`         | `{ path, logs }`      | Server                               | Called at the end of a request cycle with an array of server-side logs.
-`render:response`      | `response, { event }` | Called before sending the response.  | [response](https://github.com/nuxt/nuxt/blob/71ef8bd3ff207fd51c2ca18d5a8c7140476780c7/packages/nuxt/src/core/runtime/nitro/renderer.ts#L24), [event](https://github.com/unjs/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38)
-`render:html`          | `html, { event }`     | Called before constructing the HTML. | [html](https://github.com/nuxt/nuxt/blob/71ef8bd3ff207fd51c2ca18d5a8c7140476780c7/packages/nuxt/src/core/runtime/nitro/renderer.ts#L15), [event](https://github.com/unjs/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38)
-`render:island`        | `islandResponse, { event, islandContext }` | Called before constructing the island HTML. | [islandResponse](https://github.com/nuxt/nuxt/blob/e50cabfed1984c341af0d0c056a325a8aec26980/packages/nuxt/src/core/runtime/nitro/renderer.ts#L28), [event](https://github.com/unjs/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38), [islandContext](https://github.com/nuxt/nuxt/blob/e50cabfed1984c341af0d0c056a325a8aec26980/packages/nuxt/src/core/runtime/nitro/renderer.ts#L38)
+`render:response`      | `response, { event }` | Called before sending the response.  | [response](https://github.com/nuxt/nuxt/blob/71ef8bd3ff207fd51c2ca18d5a8c7140476780c7/packages/nuxt/src/core/runtime/nitro/renderer.ts#L24), [event](https://github.com/h3js/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38)
+`render:html`          | `html, { event }`     | Called before constructing the HTML. | [html](https://github.com/nuxt/nuxt/blob/71ef8bd3ff207fd51c2ca18d5a8c7140476780c7/packages/nuxt/src/core/runtime/nitro/renderer.ts#L15), [event](https://github.com/h3js/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38)
+`render:island`        | `islandResponse, { event, islandContext }` | Called before constructing the island HTML. | [islandResponse](https://github.com/nuxt/nuxt/blob/e50cabfed1984c341af0d0c056a325a8aec26980/packages/nuxt/src/core/runtime/nitro/renderer.ts#L28), [event](https://github.com/h3js/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38), [islandContext](https://github.com/nuxt/nuxt/blob/e50cabfed1984c341af0d0c056a325a8aec26980/packages/nuxt/src/core/runtime/nitro/renderer.ts#L38)
 `close`               | -                | Called when Nitro is closed. | -
-`error`               | `error, { event? }`          | Called when an error occurs. | [error](https://github.com/nitrojs/nitro/blob/d20ffcbd16fc4003b774445e1a01e698c2bb078a/src/types/runtime/nitro.ts#L48), [event](https://github.com/unjs/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38)
-`request`             | `event`        | Called when a request is received. | [event](https://github.com/unjs/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38)
-`beforeResponse`      | `event, { body }`        | Called before sending the response. | [event](https://github.com/unjs/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38), unknown
-`afterResponse`       | `event, { body }`        | Called after sending the response. | [event](https://github.com/unjs/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38), unknown
+`error`               | `error, { event? }`          | Called when an error occurs. | [error](https://github.com/nitrojs/nitro/blob/d20ffcbd16fc4003b774445e1a01e698c2bb078a/src/types/runtime/nitro.ts#L48), [event](https://github.com/h3js/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38)
+`request`             | `event`        | Called when a request is received. | [event](https://github.com/h3js/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38)
+`beforeResponse`      | `event, { body }`        | Called before sending the response. | [event](https://github.com/h3js/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38), unknown
+`afterResponse`       | `event, { body }`        | Called after sending the response. | [event](https://github.com/h3js/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38), unknown

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "4.0.0-29178461.f99b7b01",
+  "version": "4.0.0-29179457.2dafcc72",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",