@nuxt/docs 4.2.1 → 4.3.0

package/{2.guide/3.going-further → 3.guide/6.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({
@@ -41,11 +41,11 @@ Instead of passing non-serializable objects or functions into your application f
 
 ### Environment Variables
 
-The most common way to provide configuration is by using [Environment Variables](https://medium.com/chingu/an-introduction-to-environment-variables-and-how-to-use-them-f602f66d15fa).
+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/6.going-further}/2.hooks.md

@@ -9,7 +9,7 @@ The hooking system is powered by [unjs/hookable](https://github.com/unjs/hookabl
 
 ## Nuxt Hooks (Build Time)
 
-These hooks are available for [Nuxt Modules](/docs/4.x/guide/going-further/modules) and build context.
+These hooks are available for [Nuxt modules](/docs/4.x/guide/modules) and build context.
 
 ### Within `nuxt.config.ts`
 
@@ -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/6.going-further}/4.kit.md

@@ -3,7 +3,7 @@ title: "Nuxt Kit"
 description: "@nuxt/kit provides features for module authors."
 ---
 
-Nuxt Kit provides composable utilities to make interacting with [Nuxt Hooks](/docs/4.x/api/advanced/hooks), the [Nuxt Interface](/docs/4.x/guide/going-further/internals#the-nuxt-interface) and developing [Nuxt Modules](/docs/4.x/guide/going-further/modules) super easy.
+Nuxt Kit provides composable utilities to make interacting with [Nuxt Hooks](/docs/4.x/api/advanced/hooks), the [Nuxt Interface](/docs/4.x/guide/going-further/internals#the-nuxt-interface) and developing [Nuxt modules](/docs/4.x/guide/modules) super easy.
 
 ::read-more{to="/docs/4.x/api/kit"}
 Discover all Nuxt Kit utilities.

package/{2.guide/3.going-further → 3.guide/6.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/6.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({
@@ -249,6 +249,32 @@ export default defineNuxtConfig({
 })
 ```
 
+## Disabling Modules from Layers
+
+When extending a layer, you might want to disable certain modules that it includes. You can do this by setting the module's config key to `false` in your Nuxt config.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  extends: ['./base-layer'],
+  // Disable modules from the layer by setting their config key to false
+  image: false, // Disables @nuxt/image
+  pinia: false, // Disables @pinia/nuxt
+})
+```
+
+::note
+The config key is defined by each module. Common examples include `image` for `@nuxt/image`, `pinia` for `@pinia/nuxt`, and `content` for `@nuxt/content`. Check the module's documentation for its specific config key.
+::
+
+This is useful when:
+- A layer includes modules you don't need in your project
+- You want to use a different implementation than what the layer provides
+- You need to disable analytics or other modules in specific environments
+
+::tip
+You can also use this approach to disable modules in your own project - not just those from layers. Setting a module's config key to `false` will prevent its setup function from running while still generating types for the module.
+::
+
 ## Multi-Layer Support for Nuxt Modules
 
 You can use the [`getLayerDirectories`](/docs/4.x/api/kit/layers#getlayerdirectories) utility from Nuxt Kit to support custom multi-layer handling for your modules.

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

@@ -54,6 +54,10 @@ This component is experimental and in order to use it you must enable the `exper
   - **type**: `boolean`
   - **default**: `false`
 
+::warning{icon="i-ph-warning-duotone"}
+The `placeholder` and `fallback` props render content as raw HTML. Do not pass untrusted user input to these props as it may lead to XSS vulnerabilities. Use the `#fallback` or `#placeholder` slots instead for dynamic content that needs proper escaping.
+::
+
 ```vue
 <template>
   <!-- render <span>Hello world</span> server-side if the default slot fails to render -->

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,12 +18,12 @@ 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.
-  - **type**: `string`
+- `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, or `false` to disable the layout.
+  - **type**: `string | false`
   - **default**: `default`
 
 ```vue [app/pages/index.vue]
@@ -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}/1.components/8.nuxt-island.md

@@ -32,13 +32,20 @@ Server only components use `<NuxtIsland>` under the hood
   - **type**: `Record<string, any>`
 - `source`: Remote source to call the island to render.
   - **type**: `string`
-- **dangerouslyLoadClientComponents**: Required to load components from a remote source.
+- **dangerouslyLoadClientComponents**: Required to load client components from a remote source.
   - **type**: `boolean`
   - **default**: `false`
 
 ::note
 Remote islands need `experimental.componentIslands` to be `'local+remote'` in your `nuxt.config`.
-It is strongly discouraged to enable `dangerouslyLoadClientComponents` as you can't trust a remote server's javascript.
+::
+
+::warning{icon="i-ph-warning-duotone"}
+Using the `source` prop to render content from a remote server is inherently dangerous. When you specify a remote `source`, you are fully trusting that server to provide safe HTML content that will be rendered directly in your application.
+
+This is similar to using `v-html` with external content - the remote server can inject any HTML, including potentially malicious content. **Only use `source` with servers you fully trust and control.**
+
+The `dangerouslyLoadClientComponents` prop controls an additional layer of risk: whether to also download and execute client components from the remote source. Even with `dangerouslyLoadClientComponents` disabled (the default), you are still trusting the remote server's HTML output.
 ::
 
 ::note

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/{3.api → 4.api}/2.composables/use-async-data.md

@@ -25,8 +25,8 @@ const { data, status, pending, error, refresh, clear } = await useAsyncData(
 </script>
 ```
 
-::warning
-If you're using a custom useAsyncData wrapper, do not await it in the composable, as that can cause unexpected behavior. Please follow [this recipe](/docs/4.x/guide/recipes/custom-usefetch#custom-usefetchuseasyncdata) for more information on how to make a custom async data fetcher.
+::warning{to="/docs/4.x/guide/recipes/custom-usefetch#custom-usefetchuseasyncdata"}
+If you're using a custom `useAsyncData` wrapper, do not await it in the composable as that can cause unexpected behavior. See recipe for custom async data fetcher.
 ::
 
 ::note
@@ -148,7 +148,7 @@ The `handler` function should be **side-effect free** to ensure predictable beha
   - `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:
+  - `getCachedData`: Provide a function which returns cached data. An `undefined` return value will trigger a fetch. By default, this is:
     ```ts
     const getDefaultCachedData = (key, nuxtApp, ctx) => nuxtApp.isHydrating
       ? nuxtApp.payload.data[key]

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-error.md

@@ -22,8 +22,8 @@ You can use this composable in your components, pages, or plugins to access or r
 
 ```ts
 interface NuxtError<DataT = unknown> {
-  statusCode: number
-  statusMessage: string
+  status: number
+  statusText: string
   message: string
   data?: DataT
   error?: true