@nuxt/docs 4.2.1 → 4.2.2

package/{2.guide/3.going-further → 3.guide/5.going-further}/1.events.md

@@ -1,10 +1,9 @@
 ---
-title: "Events"
+title: "Creating Custom Events"
 description: "Nuxt provides a powerful event system powered by hookable."
+navigation.title: "Custom Events"
 ---
 
-# Events
-
 Using events is a great way to decouple your application and allow for more flexible and modular communication between different parts of your code. Events can have multiple listeners that do not depend on each other. For example, you may wish to send an email to your user each time an order has shipped. Instead of coupling your order processing code to your email code, you can emit an event which a listener can receive and use to dispatch an email.
 
 The Nuxt event system is powered by [unjs/hookable](https://github.com/unjs/hookable), which is the same library that powers the Nuxt hooks system.

package/{2.guide/3.going-further → 3.guide/5.going-further}/1.experimental-features.md

@@ -131,7 +131,7 @@ Emits `app:chunkError` hook when there is an error loading vite/webpack chunks.
 
 By default, Nuxt will also perform a reload of the new route when a chunk fails to load when navigating to a new route (`automatic`).
 
-Setting `automatic-immediate` will lead Nuxt to perform a reload of the current route right when a chunk fails to load (instead of waiting for navigation). This is useful for chunk errors that are not triggered by navigation, e.g., when your Nuxt app fails to load a [lazy component](/docs/4.x/guide/directory-structure/app/components#dynamic-imports). A potential downside of this behavior is undesired reloads, e.g., when your app does not need the chunk that caused the error.
+Setting `automatic-immediate` will lead Nuxt to perform a reload of the current route right when a chunk fails to load (instead of waiting for navigation). This is useful for chunk errors that are not triggered by navigation, e.g., when your Nuxt app fails to load a [lazy component](/docs/4.x/directory-structure/app/components#dynamic-imports). A potential downside of this behavior is undesired reloads, e.g., when your app does not need the chunk that caused the error.
 
 You can disable automatic handling by setting this to `false`, or handle chunk errors manually by setting it to `manual`.
 
@@ -318,7 +318,7 @@ export default defineNuxtConfig({
 })
 ```
 
-:read-more{to="/docs/4.x/guide/directory-structure/app/components#server-components"}
+:read-more{to="/docs/4.x/directory-structure/app/components#server-components"}
 
 ::read-more{icon="i-simple-icons-github" to="https://github.com/nuxt/nuxt/issues/19772" target="_blank"}
 You can follow the server components roadmap on GitHub.
@@ -541,7 +541,7 @@ export default defineNuxtConfig({
 })
 ```
 
-This allows modules to access additional metadata from the page metadata in the build context. If you are using this within a module, it's recommended also to [augment the `NuxtPage` types with your keys](/docs/4.x/guide/directory-structure/app/pages#typing-custom-metadata).
+This allows modules to access additional metadata from the page metadata in the build context. If you are using this within a module, it's recommended also to [augment the `NuxtPage` types with your keys](/docs/4.x/directory-structure/app/pages#typing-custom-metadata).
 
 ## navigationRepaint
 
@@ -665,7 +665,7 @@ export default defineNuxtConfig({
 })
 ```
 
-::read-more{icon="i-simple-icons-github" color="gray" to="/docs/4.x/guide/directory-structure/app/components#delayed-or-lazy-hydration"}
+::read-more{icon="i-simple-icons-github" color="gray" to="/docs/4.x/directory-structure/app/components#delayed-or-lazy-hydration"}
 Read more about lazy hydration.
 ::
 

package/{2.guide/3.going-further → 3.guide/5.going-further}/1.internals.md

@@ -1,6 +1,7 @@
 ---
 title: "How Nuxt Works?"
 description: "Nuxt is a minimal but highly customizable framework to build web applications."
+navigation: false
 ---
 
 This guide helps you better understand Nuxt internals to develop new solutions and module integrations on top of Nuxt.
@@ -30,7 +31,7 @@ Global usage is possible for the browser but not on the server, to avoid sharing
 
 Since [`useNuxtApp`](/docs/4.x/api/composables/use-nuxt-app) throws an exception if context is currently unavailable, if your composable does not always require `nuxtApp`, you can use [`tryUseNuxtApp`](/docs/4.x/api/composables/use-nuxt-app#tryusenuxtapp) instead, which will return `null` instead of throwing an exception.
 
-To extend the `nuxtApp` interface and hook into different stages or access contexts, we can use [Nuxt Plugins](/docs/4.x/guide/directory-structure/app/plugins).
+To extend the `nuxtApp` interface and hook into different stages or access contexts, we can use [Nuxt Plugins](/docs/4.x/directory-structure/app/plugins).
 
 Check [Nuxt App](/docs/4.x/api/composables/use-nuxt-app) for more information about this interface.
 
@@ -76,6 +77,6 @@ Nuxt builds and bundles project using Node.js but also has a runtime side.
 
 While both areas can be extended, that runtime context is isolated from build-time. Therefore, they are not supposed to share state, code, or context other than runtime configuration!
 
-`nuxt.config` and [Nuxt Modules](/docs/4.x/guide/going-further/modules) can be used to extend the build context, and [Nuxt Plugins](/docs/4.x/guide/directory-structure/app/plugins) can be used to extend runtime.
+`nuxt.config` and [Nuxt Modules](/docs/4.x/guide/going-further/modules) can be used to extend the build context, and [Nuxt Plugins](/docs/4.x/directory-structure/app/plugins) can be used to extend runtime.
 
 When building an application for production, `nuxt build` will generate a standalone build in the `.output` directory, independent of `nuxt.config` and [Nuxt modules](/docs/4.x/guide/going-further/modules).

package/{2.guide/3.going-further → 3.guide/5.going-further}/10.runtime-config.md

@@ -5,7 +5,7 @@ description: "Nuxt provides a runtime config API to expose configuration and sec
 
 ## Exposing
 
-To expose config and environment variables to the rest of your app, you will need to define runtime configuration in your [`nuxt.config`](/docs/4.x/guide/directory-structure/nuxt-config) file, using the [`runtimeConfig`](/docs/4.x/api/nuxt-config#runtimeconfig) option.
+To expose config and environment variables to the rest of your app, you will need to define runtime configuration in your [`nuxt.config`](/docs/4.x/directory-structure/nuxt-config) file, using the [`runtimeConfig`](/docs/4.x/api/nuxt-config#runtimeconfig) option.
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -45,7 +45,7 @@ The most common way to provide configuration is by using [Environment Variables]
 
 ::note
 The Nuxt CLI has built-in support for reading your `.env` file in development, build and generate. But when you run your built server, **your `.env` file will not be read**.
-:read-more{to="/docs/4.x/guide/directory-structure/env"}
+:read-more{to="/docs/4.x/directory-structure/env"}
 ::
 
 Runtime config values are **automatically replaced by matching environment variables at runtime**.

package/{2.guide/3.going-further → 3.guide/5.going-further}/2.hooks.md

@@ -39,7 +39,7 @@ Explore all available Nuxt hooks.
 
 ## App Hooks (Runtime)
 
-App hooks can be mainly used by [Nuxt Plugins](/docs/4.x/guide/directory-structure/app/plugins) to hook into rendering lifecycle but could also be used in Vue composables.
+App hooks can be mainly used by [Nuxt Plugins](/docs/4.x/directory-structure/app/plugins) to hook into rendering lifecycle but could also be used in Vue composables.
 
 ```ts [app/plugins/test.ts]
 export default defineNuxtPlugin((nuxtApp) => {
@@ -55,7 +55,7 @@ Explore all available App hooks.
 
 ## Server Hooks (Runtime)
 
-These hooks are available for [server plugins](/docs/4.x/guide/directory-structure/server#server-plugins) to hook into Nitro's runtime behavior.
+These hooks are available for [server plugins](/docs/4.x/directory-structure/server#server-plugins) to hook into Nitro's runtime behavior.
 
 ```ts [~/server/plugins/test.ts]
 export default defineNitroPlugin((nitroApp) => {

package/{2.guide/3.going-further → 3.guide/5.going-further}/3.modules.md

@@ -117,7 +117,7 @@ Nuxt Modules come with a variety of powerful APIs and patterns allowing them to
 We can consider two kinds of Nuxt Modules:
 
 - published modules are distributed on npm - you can see a list of some community modules on [the Nuxt website](/modules).
-- "local" modules, they exist within a Nuxt project itself, either [inlined in Nuxt config](/docs/4.x/api/nuxt-config#modules) or as part of [the `modules` directory](/docs/4.x/guide/directory-structure/modules).
+- "local" modules, they exist within a Nuxt project itself, either [inlined in Nuxt config](/docs/4.x/api/nuxt-config#modules) or as part of [the `modules` directory](/docs/4.x/directory-structure/modules).
 
 In either case, their anatomy is similar.
 
@@ -224,7 +224,7 @@ Modules, like everything in a Nuxt configuration, aren't included in your applic
 Inside the runtime directory, you can provide any kind of assets related to the Nuxt App:
 - Vue components
 - Composables
-- [Nuxt plugins](/docs/4.x/guide/directory-structure/app/plugins)
+- [Nuxt plugins](/docs/4.x/directory-structure/app/plugins)
 
 To the [server engine](/docs/4.x/guide/concepts/server-engine), Nitro:
 - API routes

package/{2.guide/3.going-further → 3.guide/5.going-further}/6.nuxt-app.md

@@ -23,7 +23,7 @@ Jump over the `NuxtApp` interface documentation.
 
 Many composables and utilities, both built-in and user-made, may require access to the Nuxt instance. This doesn't exist everywhere on your application, because a fresh instance is created on every request.
 
-Currently, the Nuxt context is only accessible in [plugins](/docs/4.x/guide/directory-structure/app/plugins), [Nuxt hooks](/docs/4.x/guide/going-further/hooks), [Nuxt middleware](/docs/4.x/guide/directory-structure/app/middleware) (if wrapped in `defineNuxtRouteMiddleware`), and [setup functions](https://vuejs.org/api/composition-api-setup) (in pages and components).
+Currently, the Nuxt context is only accessible in [plugins](/docs/4.x/directory-structure/app/plugins), [Nuxt hooks](/docs/4.x/guide/going-further/hooks), [Nuxt middleware](/docs/4.x/directory-structure/app/middleware) (if wrapped in `defineNuxtRouteMiddleware`), and [setup functions](https://vuejs.org/api/composition-api-setup) (in pages and components).
 
 If a composable is called without access to the context, you may get an error stating that 'A composable that requires access to the Nuxt instance was called outside of a plugin, Nuxt hook, Nuxt middleware, or Vue setup function.' In that case, you can also explicitly call functions within this context by using [`nuxtApp.runWithContext`](/docs/4.x/api/composables/use-nuxt-app#runwithcontext).
 
@@ -42,7 +42,7 @@ If your composable does not always need `nuxtApp` or you simply want to check if
 
 Plugins also receive `nuxtApp` as the first argument for convenience.
 
-:read-more{to="/docs/4.x/guide/directory-structure/app/plugins"}
+:read-more{to="/docs/4.x/directory-structure/app/plugins"}
 
 ## Providing Helpers
 
@@ -55,7 +55,7 @@ nuxtApp.provide('hello', name => `Hello ${name}!`)
 console.log(nuxtApp.$hello('name')) // Prints "Hello name!"
 ```
 
-::read-more{to="/docs/4.x/guide/directory-structure/app/plugins#providing-helpers"}
+::read-more{to="/docs/4.x/directory-structure/app/plugins#providing-helpers"}
 It is possible to inject helpers by returning an object with a `provide` key in plugins.
 ::
 

package/{2.guide/3.going-further → 3.guide/5.going-further}/7.layers.md

@@ -7,7 +7,7 @@ Nuxt layers are a powerful feature that you can use to share and reuse partial N
 
 :read-more{to="/docs/4.x/getting-started/layers"}
 
-A minimal Nuxt layer directory should contain a [`nuxt.config.ts`](/docs/4.x/guide/directory-structure/nuxt-config) file to indicate it is a layer.
+A minimal Nuxt layer directory should contain a [`nuxt.config.ts`](/docs/4.x/directory-structure/nuxt-config) file to indicate it is a layer.
 
 ```ts [base/nuxt.config.ts]
 export default defineNuxtConfig({})
@@ -15,20 +15,20 @@ export default defineNuxtConfig({})
 
 Additionally, certain other files in the layer directory will be auto-scanned and used by Nuxt for the project extending this layer.
 
-- [`app/components/*`](/docs/4.x/guide/directory-structure/app/components)   - Extend the default components
-- [`app/composables/*`](/docs/4.x/guide/directory-structure/app/composables)  - Extend the default composables
-- [`app/layouts/*`](/docs/4.x/guide/directory-structure/app/layouts)  - Extend the default layouts
-- [`app/middleware/*`](/docs/4.x/guide/directory-structure/app/middleware)  - Extend the default middleware
-- [`app/pages/*`](/docs/4.x/guide/directory-structure/app/pages)        - Extend the default pages
-- [`app/plugins/*`](/docs/4.x/guide/directory-structure/app/plugins)        - Extend the default plugins
-- [`app/utils/*`](/docs/4.x/guide/directory-structure/app/utils)   - Extend the default utils
-- [`app/app.config.ts`](/docs/4.x/guide/directory-structure/app/app-config)  - Extend the default app config
-- [`server/*`](/docs/4.x/guide/directory-structure/server)       - Extend the default server endpoints & middleware
-- [`nuxt.config.ts`](/docs/4.x/guide/directory-structure/nuxt-config)- Extend the default nuxt config
+- [`app/components/*`](/docs/4.x/directory-structure/app/components)   - Extend the default components
+- [`app/composables/*`](/docs/4.x/directory-structure/app/composables)  - Extend the default composables
+- [`app/layouts/*`](/docs/4.x/directory-structure/app/layouts)  - Extend the default layouts
+- [`app/middleware/*`](/docs/4.x/directory-structure/app/middleware)  - Extend the default middleware
+- [`app/pages/*`](/docs/4.x/directory-structure/app/pages)        - Extend the default pages
+- [`app/plugins/*`](/docs/4.x/directory-structure/app/plugins)        - Extend the default plugins
+- [`app/utils/*`](/docs/4.x/directory-structure/app/utils)   - Extend the default utils
+- [`app/app.config.ts`](/docs/4.x/directory-structure/app/app-config)  - Extend the default app config
+- [`server/*`](/docs/4.x/directory-structure/server)       - Extend the default server endpoints & middleware
+- [`nuxt.config.ts`](/docs/4.x/directory-structure/nuxt-config)- Extend the default nuxt config
 
 ## Basic Example
 
-::code-group
+::code-tree{defaultValue="nuxt.config.ts" expandAll}
 
   ```ts [nuxt.config.ts]
   export default defineNuxtConfig({

package/{3.api → 4.api}/1.components/12.nuxt-route-announcer.md

@@ -1,8 +1,6 @@
 ---
 title: '<NuxtRouteAnnouncer>'
 description: 'The <NuxtRouteAnnouncer> component adds a hidden element with the page title to announce route changes to assistive technologies.'
-navigation:
-  badge: New
 links:
   - label: Source
     icon: i-simple-icons-github
@@ -16,7 +14,7 @@ This component is available in Nuxt v3.12+.
 
 ## Usage
 
-Add `<NuxtRouteAnnouncer/>` in your [`app.vue`](/docs/4.x/guide/directory-structure/app/app) or [`app/layouts/`](/docs/4.x/guide/directory-structure/app/layouts) to enhance accessibility by informing assistive technologies about page title changes. This ensures that navigational changes are announced to users relying on screen readers.
+Add `<NuxtRouteAnnouncer/>` in your [`app.vue`](/docs/4.x/directory-structure/app/app) or [`app/layouts/`](/docs/4.x/directory-structure/app/layouts) to enhance accessibility by informing assistive technologies about page title changes. This ensures that navigational changes are announced to users relying on screen readers.
 
 ```vue [app/app.vue]
 <template>

package/{3.api → 4.api}/1.components/13.nuxt-time.md

@@ -1,8 +1,6 @@
 ---
 title: '<NuxtTime>'
 description: 'The <NuxtTime> component displays time in a locale-friendly format with server-client consistency.'
-navigation:
-  badge: New
 links:
   - label: Source
     icon: i-simple-icons-github

package/{3.api → 4.api}/1.components/2.nuxt-page.md

@@ -8,7 +8,7 @@ links:
     size: xs
 ---
 
-`<NuxtPage>` is a built-in component that comes with Nuxt. It lets you display top-level or nested pages located in the [`app/pages/`](/docs/4.x/guide/directory-structure/app/pages) directory.
+`<NuxtPage>` is a built-in component that comes with Nuxt. It lets you display top-level or nested pages located in the [`app/pages/`](/docs/4.x/directory-structure/app/pages) directory.
 
 ::note
 `<NuxtPage>` is a wrapper around [`<RouterView>`](https://router.vuejs.org/api/interfaces/routerviewprops) from Vue Router. It should be used instead of `<RouterView>` because the former takes additional care of internal states. Otherwise, `useRoute()` may return incorrect paths.
@@ -151,4 +151,4 @@ console.log(attrs.foobar) // Outputs: 123
 </script>
 ```
 
-:read-more{to="/docs/4.x/guide/directory-structure/app/pages"}
+:read-more{to="/docs/4.x/directory-structure/app/pages"}

package/{3.api → 4.api}/1.components/3.nuxt-layout.md

@@ -18,11 +18,11 @@ You can use `<NuxtLayout />` component to activate the `default` layout on `app.
 </template>
 ```
 
-:read-more{to="/docs/4.x/guide/directory-structure/app/layouts"}
+:read-more{to="/docs/4.x/directory-structure/app/layouts"}
 
 ## Props
 
-- `name`: Specify a layout name to be rendered, can be a string, reactive reference or a computed property. It **must** match the name of the corresponding layout file in the [`app/layouts/`](/docs/4.x/guide/directory-structure/app/layouts) directory.
+- `name`: Specify a layout name to be rendered, can be a string, reactive reference or a computed property. It **must** match the name of the corresponding layout file in the [`app/layouts/`](/docs/4.x/directory-structure/app/layouts) directory.
   - **type**: `string`
   - **default**: `default`
 
@@ -51,11 +51,11 @@ Please note the layout name is normalized to kebab-case, so if your layout file
 </template>
 ```
 
-::read-more{to="/docs/4.x/guide/directory-structure/app/layouts"}
+::read-more{to="/docs/4.x/directory-structure/app/layouts"}
 Read more about dynamic layouts.
 ::
 
-- `fallback`: If an invalid layout is passed to the `name` prop, no layout will be rendered. Specify a `fallback` layout to be rendered in this scenario. It **must** match the name of the corresponding layout file in the [`app/layouts/`](/docs/4.x/guide/directory-structure/app/layouts) directory.
+- `fallback`: If an invalid layout is passed to the `name` prop, no layout will be rendered. Specify a `fallback` layout to be rendered in this scenario. It **must** match the name of the corresponding layout file in the [`app/layouts/`](/docs/4.x/directory-structure/app/layouts) directory.
   - **type**: `string`
   - **default**: `null`
 
@@ -158,4 +158,4 @@ defineExpose({
 
 ::
 
-:read-more{to="/docs/4.x/guide/directory-structure/app/layouts"}
+:read-more{to="/docs/4.x/directory-structure/app/layouts"}

package/{3.api → 4.api}/1.components/5.nuxt-loading-indicator.md

@@ -10,7 +10,7 @@ links:
 
 ## Usage
 
-Add `<NuxtLoadingIndicator/>` in your [`app.vue`](/docs/4.x/guide/directory-structure/app/app) or [`app/layouts/`](/docs/4.x/guide/directory-structure/app/layouts).
+Add `<NuxtLoadingIndicator/>` in your [`app.vue`](/docs/4.x/directory-structure/app/app) or [`app/layouts/`](/docs/4.x/directory-structure/app/layouts).
 
 ```vue [app/app.vue]
 <template>

package/{3.api → 4.api}/1.components/7.nuxt-welcome.md

@@ -4,7 +4,7 @@ description: The <NuxtWelcome> component greets users in new projects made from
 links:
   - label: Source
     icon: i-simple-icons-github
-    to: https://github.com/nuxt/assets/blob/main/packages/templates/templates/welcome/index.html
+    to: https://github.com/nuxt/nuxt/blob/main/packages/ui-templates/templates/welcome/index.html
     size: xs
 ---
 
@@ -21,5 +21,5 @@ Preview the `<NuxtWelcome />` component.
 ::
 
 ::tip
-This component is part of [nuxt/assets](https://github.com/nuxt/assets).
+This component is part of [`@nuxt/ui-templates`](https://github.com/nuxt/nuxt/tree/main/packages/ui-templates) package.
 ::

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

@@ -16,4 +16,4 @@ const appConfig = useAppConfig()
 console.log(appConfig)
 ```
 
-:read-more{to="/docs/4.x/guide/directory-structure/app/app-config"}
+:read-more{to="/docs/4.x/directory-structure/app/app-config"}

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/4.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/4.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/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/4.x/examples/advanced/use-cookie"}

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

@@ -183,29 +183,29 @@ type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'
 
 - `options` (object): Configuration for the fetch request. Extends [unjs/ofetch](https://github.com/unjs/ofetch) options and [`AsyncDataOptions`](/docs/4.x/api/composables/use-async-data#params). All options can be a static value, a `ref`, or a computed value.
 
-| Option | Type | Default | Description |
-| ---| --- | --- | --- |
-| `key` | `MaybeRefOrGetter<string>` | auto-gen | Unique key for de-duplication. If not provided, generated from URL and options. |
-| `method` | `MaybeRefOrGetter<string>` | `'GET'` | HTTP request method. |
-| `query` | `MaybeRefOrGetter<SearchParams>` | - | Query/search params to append to the URL. Alias: `params`. |
-| `params` | `MaybeRefOrGetter<SearchParams>` | - | Alias for `query`. |
-| `body` | `MaybeRefOrGetter<RequestInit['body'] \| Record<string, any>>` | - | Request body. Objects are automatically stringified. |
-| `headers` | `MaybeRefOrGetter<Record<string, string> \| [key, value][] \| Headers>` | - | Request headers. |
-| `baseURL` | `MaybeRefOrGetter<string>` | - | Base URL for the request. |
-| `timeout` | `MaybeRefOrGetter<number>` | - | Timeout in milliseconds to abort the request. |
-| `cache` | `boolean \| string` | - | Cache control. Boolean disables cache, or use Fetch API values: `default`, `no-store`, etc. |
-| `server` | `boolean` | `true` | Whether to fetch on the server. |
-| `lazy` | `boolean` | `false` | If true, resolves after route loads (does not block navigation). |
-| `immediate` | `boolean` | `true` | If false, prevents request from firing immediately. |
-| `default` | `() => DataT` | - | Factory for default value of `data` before async resolves. |
-| `timeout` | `number` | - | A number in milliseconds to wait before timing out the request (defaults to `undefined`, which means no timeout) |
-| `transform` | `(input: DataT) => DataT \| Promise<DataT>` | - | Function to transform the result after resolving. |
-| `getCachedData`| `(key, nuxtApp, ctx) => DataT \| undefined` | - | Function to return cached data. See below for default. |
-| `pick` | `string[]` | - | Only pick specified keys from the result. |
-| `watch` | `MultiWatchSources \| false` | - | Array of reactive sources to watch and auto-refresh. `false` disables watching. |
-| `deep` | `boolean` | `false` | Return data in a deep ref object. |
-| `dedupe` | `'cancel' \| 'defer'` | `'cancel'` | Avoid fetching same key more than once at a time. |
-| `$fetch` | `typeof globalThis.$fetch` | - | Custom $fetch implementation. See [Custom useFetch in Nuxt](/docs/4.x/guide/recipes/custom-usefetch) |
+| Option          | Type                                                                    | Default    | Description                                                                                                      |
+|-----------------|-------------------------------------------------------------------------|------------|------------------------------------------------------------------------------------------------------------------|
+| `key`           | `MaybeRefOrGetter<string>`                                              | auto-gen   | Unique key for de-duplication. If not provided, generated from URL and options.                                  |
+| `method`        | `MaybeRefOrGetter<string>`                                              | `'GET'`    | HTTP request method.                                                                                             |
+| `query`         | `MaybeRefOrGetter<SearchParams>`                                        | -          | Query/search params to append to the URL. Alias: `params`.                                                       |
+| `params`        | `MaybeRefOrGetter<SearchParams>`                                        | -          | Alias for `query`.                                                                                               |
+| `body`          | `MaybeRefOrGetter<RequestInit['body'] \| Record<string, any>>`          | -          | Request body. Objects are automatically stringified.                                                             |
+| `headers`       | `MaybeRefOrGetter<Record<string, string> \| [key, value][] \| Headers>` | -          | Request headers.                                                                                                 |
+| `baseURL`       | `MaybeRefOrGetter<string>`                                              | -          | Base URL for the request.                                                                                        |
+| `timeout`       | `MaybeRefOrGetter<number>`                                              | -          | Timeout in milliseconds to abort the request.                                                                    |
+| `cache`         | `boolean \| string`                                                     | -          | Cache control. Boolean disables cache, or use Fetch API values: `default`, `no-store`, etc.                      |
+| `server`        | `boolean`                                                               | `true`     | Whether to fetch on the server.                                                                                  |
+| `lazy`          | `boolean`                                                               | `false`    | If true, resolves after route loads (does not block navigation).                                                 |
+| `immediate`     | `boolean`                                                               | `true`     | If false, prevents request from firing immediately.                                                              |
+| `default`       | `() => DataT`                                                           | -          | Factory for default value of `data` before async resolves.                                                       |
+| `timeout`       | `number`                                                                | -          | A number in milliseconds to wait before timing out the request (defaults to `undefined`, which means no timeout) |
+| `transform`     | `(input: DataT) => DataT \| Promise<DataT>`                             | -          | Function to transform the result after resolving.                                                                |
+| `getCachedData` | `(key, nuxtApp, ctx) => DataT \| undefined`                             | -          | Function to return cached data. See below for default.                                                           |
+| `pick`          | `string[]`                                                              | -          | Only pick specified keys from the result.                                                                        |
+| `watch`         | `MultiWatchSources \| false`                                            | -          | Array of reactive sources to watch and auto-refresh. `false` disables watching.                                  |
+| `deep`          | `boolean`                                                               | `false`    | Return data in a deep ref object.                                                                                |
+| `dedupe`        | `'cancel' \| 'defer'`                                                   | `'cancel'` | Avoid fetching same key more than once at a time.                                                                |
+| `$fetch`        | `typeof globalThis.$fetch`                                              | -          | Custom $fetch implementation. See [Custom useFetch in Nuxt](/docs/4.x/guide/recipes/custom-usefetch)             |
 
 ::note
 All fetch options can be given a `computed` or `ref` value. These will be watched and new requests made automatically with any new values if they are updated.
@@ -222,14 +222,14 @@ This only caches data when `experimental.payloadExtraction` in `nuxt.config` is
 
 ## Return Values
 
-| Name | Type | Description |
-| --- | --- |--- |
-| `data` | `Ref<DataT \| undefined>` | The result of the asynchronous fetch. |
-| `refresh` | `(opts?: AsyncDataExecuteOptions) => Promise<void>` | Function to manually refresh the data. By default, Nuxt waits until a `refresh` is finished before it can be executed again. |
-| `execute` | `(opts?: AsyncDataExecuteOptions) => Promise<void>` | Alias for `refresh`. |
-| `error` | `Ref<ErrorT \| undefined>` | Error object if the data fetching failed. |
-| `status` | `Ref<'idle' \| 'pending' \| 'success' \| 'error'>` | Status of the data request. See below for possible values. |
-| `clear` | `() => void` | Resets `data` to `undefined` (or the value of `options.default()` if provided), `error` to `undefined`, set `status` to `idle`, and cancels any pending requests. |
+| Name      | Type                                                | Description                                                                                                                                                       |
+|-----------|-----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `data`    | `Ref<DataT \| undefined>`                           | The result of the asynchronous fetch.                                                                                                                             |
+| `refresh` | `(opts?: AsyncDataExecuteOptions) => Promise<void>` | Function to manually refresh the data. By default, Nuxt waits until a `refresh` is finished before it can be executed again.                                      |
+| `execute` | `(opts?: AsyncDataExecuteOptions) => Promise<void>` | Alias for `refresh`.                                                                                                                                              |
+| `error`   | `Ref<ErrorT \| undefined>`                          | Error object if the data fetching failed.                                                                                                                         |
+| `status`  | `Ref<'idle' \| 'pending' \| 'success' \| 'error'>`  | Status of the data request. See below for possible values.                                                                                                        |
+| `clear`   | `() => void`                                        | Resets `data` to `undefined` (or the value of `options.default()` if provided), `error` to `undefined`, set `status` to `idle`, and cancels any pending requests. |
 
 ### Status values