@nuxt/docs-nightly 4.2.1-29370805.6a102676 → 4.2.1-29370820.95518afa

package/1.getting-started/18.upgrade.md

@@ -1212,22 +1212,30 @@ However, to take advantage of improved type checking, you can opt in to the new
     Augmenting types from outside the `app/`, `server/`, or `shared/` directories will not work with the new project references setup.
     ::
 
-5. **Configure Node.js TypeScript options** if needed:
+5. **Configure TypeScript options** if needed:
    <!-- @case-police-ignore tsConfig -->
 
    ```ts
    export default defineNuxtConfig({
      typescript: {
-       // Customize app/server TypeScript config
+       // customize tsconfig.app.json
        tsConfig: {
-         compilerOptions: {
-           strict: true,
-         },
+         // ...
+       },
+       // customize tsconfig.shared.json
+       sharedTsConfig: {
+         // ...
        },
-       // Customize build-time TypeScript config
+       // customize tsconfig.node.json
        nodeTsConfig: {
-         compilerOptions: {
-           strict: true,
+         // ...
+       },
+     },
+     nitro: {
+       typescript: {
+         // customize tsconfig.server.json
+         tsConfig: {
+           // ...
          },
        },
      },

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

@@ -5,7 +5,7 @@ head.title: "node_modules/"
 navigation.icon: i-vscode-icons-folder-type-node
 ---
 
-The package manager ([`npm`](https://docs.npmjs.com/cli/commands/npm) or [`yarn`](https://yarnpkg.com) or [`pnpm`](https://pnpm.io/cli/install) or [`bun`](https://bun.com/package-manager)) creates this directory to store the dependencies of your project.
+The package manager ([`npm`](https://docs.npmjs.com/cli/commands/npm/) or [`yarn`](https://yarnpkg.com) or [`pnpm`](https://pnpm.io/cli/install) or [`bun`](https://bun.com/package-manager)) creates this directory to store the dependencies of your project.
 
 ::important
 This directory should be added to your [`.gitignore`](/docs/4.x/guide/directory-structure/gitignore) file to avoid pushing the dependencies to your repository.

package/2.guide/1.directory-structure/3.tsconfig.md

@@ -1,13 +1,13 @@
 ---
 title: "tsconfig.json"
-description: "Nuxt generates multiple TypeScript configuration files with sensible defaults and your aliases."
+description: "Learn how Nuxt manages TypeScript configuration across different parts of your project."
 head.title: "tsconfig.json"
 navigation.icon: i-vscode-icons-file-type-tsconfig
 ---
 
-Nuxt [automatically generates](/docs/4.x/guide/concepts/typescript) multiple TypeScript configuration files (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, `.nuxt/tsconfig.node.json` and `.nuxt/tsconfig.shared.json`) with the resolved aliases you are using in your Nuxt project, as well as with other sensible defaults.
+Nuxt [automatically generates](/docs/4.x/guide/concepts/typescript#auto-generated-types) multiple TypeScript configuration files (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, `.nuxt/tsconfig.node.json` and `.nuxt/tsconfig.shared.json`) that include recommended basic TypeScript configuration for your project, references to [auto-imports](/docs/4.x/guide/concepts/auto-imports), [API route types](/docs/4.x/guide/concepts/server-engine#typed-api-routes), path aliases, and more.
 
-You can benefit from this by creating a `tsconfig.json` in the root of your project with the following content:
+Your Nuxt project should include the following `tsconfig.json` file at the root of the project:
 
 ```json [tsconfig.json]
 {
@@ -29,10 +29,41 @@ You can benefit from this by creating a `tsconfig.json` in the root of your proj
 }
 ```
 
-::note
-As you need to, you can customize the contents of this file. However, it is recommended that you don't overwrite `target`, `module` and `moduleResolution`.
+::warning
+We do not recommend modifying the contents of this file directly, as doing so could overwrite important settings that Nuxt or other modules rely on. Instead, extend it via `nuxt.config.ts`.
 ::
 
-::note
-If you need to customize your `paths`, this will override the auto-generated path aliases. Instead, we recommend that you add any path aliases you need to the [`alias`](/docs/4.x/api/nuxt-config#alias) property within your `nuxt.config`, where they will get picked up and added to the auto-generated `tsconfig`.
+::read-more{to="/docs/4.x/guide/concepts/typescript#project-references"}
+Read more about the different type contexts of a Nuxt project here.
 ::
+
+## Extending TypeScript Configuration
+
+You can customize the TypeScript configuration of your Nuxt project for each context (`app`, `shared`, `node`, and `server`) in the `nuxt.config.ts` file.
+<!-- @case-police-ignore tsConfig -->
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  typescript: {
+    // customize tsconfig.app.json
+    tsConfig: {
+      // ...
+    },
+    // customize tsconfig.shared.json
+    sharedTsConfig: {
+      // ...
+    },
+    // customize tsconfig.node.json
+    nodeTsConfig: {
+      // ...
+    },
+  },
+  nitro: {
+    typescript: {
+      // customize tsconfig.server.json
+      tsConfig: {
+        // ...
+      },
+    },
+  },
+})
+```

package/2.guide/2.concepts/8.typescript.md

@@ -47,56 +47,37 @@ export default defineNuxtConfig({
 
 ## Auto-generated Types
 
-When you run `nuxt dev` or `nuxt build`, Nuxt generates the following files for IDE type support (and type checking):
+Nuxt projects rely on auto-generated types to work properly. These types are stored in the [`.nuxt`](/docs/4.x/guide/directory-structure/nuxt) directory and are generated when you run the dev server or build your application. You can also generate these files manually by running `nuxt prepare`.
 
-### `.nuxt/nuxt.d.ts`
+The generated `tsconfig.json` files inside the [`.nuxt`](/docs/4.x/guide/directory-structure/nuxt) directory include **recommended basic TypeScript configuration** for your project, references to [auto-imports](/docs/4.x/guide/concepts/auto-imports), [API route types](/docs/4.x/guide/concepts/server-engine#typed-api-routes), path aliases like `#imports`, `~/file`, or `#build/file`, and more.
 
-This file contains the types of any modules you are using, as well as the key types that Nuxt requires. Your IDE should recognize these types automatically.
-
-Some of the references in the file are to files that are only generated within your `buildDir` (`.nuxt`) and therefore for full typings, you will need to run `nuxt dev` or `nuxt build`.
-
-### `.nuxt/tsconfig.app.json`
-
-This file contains the recommended basic TypeScript configuration for your project, including resolved aliases injected by Nuxt or modules you are using, so you can get full type support and path auto-complete for aliases like `~/file` or `#build/file`.
-
-::note
-Consider using the `imports` section of [nuxt.config](/docs/4.x/api/nuxt-config#imports) to include directories beyond the default ones. This can be useful for auto-importing types which you're using across your app.
+::warning
+Nuxt relies on this configuration, and [Nuxt Modules](/docs/4.x/guide/going-further/modules) can extend it as well. For this reason, it is not recommended to modify your `tsconfig.json` file directly, as doing so could overwrite important settings. Instead, extend it via `nuxt.config.ts`. [Learn more about extending the configuration here](/docs/4.x/guide/directory-structure/tsconfig).
 ::
 
-[Read more about how to extend this configuration](/docs/4.x/guide/directory-structure/tsconfig).
-
 ::tip{icon="i-lucide-video" to="https://youtu.be/umLI7SlPygY" target="_blank"}
 Watch a video from Daniel Roe explaining built-in Nuxt aliases.
 ::
 
-::note
-Nitro also [auto-generates types](/docs/4.x/guide/concepts/server-engine#typed-api-routes) for API routes. Plus, Nuxt also generates types for globally available components and [auto-imports from your composables](/docs/4.x/guide/directory-structure/app/composables), plus other core functionality.
-::
-
-::note
-For backward compatibility, Nuxt still generates `./.nuxt/tsconfig.json`. However, we recommend using [TypeScript project references](/docs/4.x/guide/directory-structure/tsconfig) with the new configuration files (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, etc.) for better type safety and performance.
-
-If you do extend from `./.nuxt/tsconfig.json`, keep in mind that all options will be overwritten by those defined in your `tsconfig.json`. Overwriting options such as `"compilerOptions.paths"` with your own configuration will lead TypeScript to not factor in the module resolutions, which can cause module resolutions such as `#imports` to not be recognized.
-
-In case you need to extend options further, you can use the [`alias` property](/docs/4.x/api/nuxt-config#alias) within your `nuxt.config`. Nuxt will pick them up and extend the generated TypeScript configurations accordingly.
-::
-
 ## Project References
 
 Nuxt uses [TypeScript project references](https://www.typescriptlang.org/docs/handbook/project-references.html) to improve type-checking performance and provide better IDE support. This feature allows TypeScript to break up your codebase into smaller, more manageable pieces.
 
 ### How Nuxt Uses Project References
 
-When you run `nuxt dev` or `nuxt build`, Nuxt will generate multiple `tsconfig.json` files for different parts of your application.
+When you run `nuxt dev`, `nuxt build` or `nuxt prepare`, Nuxt will generate multiple `tsconfig.json` files for different parts of your application.
 
-- **`.nuxt/tsconfig.app.json`** - Configuration for your application code
-- **`.nuxt/tsconfig.node.json`** - Configuration for your `nuxt.config` and modules
+- **`.nuxt/tsconfig.app.json`** - Configuration for your application code within the `app/` directory
+- **`.nuxt/tsconfig.node.json`** - Configuration for your `nuxt.config.ts` and files outside the other contexts
 - **`.nuxt/tsconfig.server.json`** - Configuration for server-side code (when applicable)
 - **`.nuxt/tsconfig.shared.json`** - For code shared between app and server contexts (like types and non-environment specific utilities)
-- **`.nuxt/tsconfig.json`** - Legacy configuration for backward compatibility
 
 Each of these files is configured to reference the appropriate dependencies and provide optimal type-checking for their specific context.
 
+::note
+For backward compatibility, Nuxt still generates `.nuxt/tsconfig.json`. However, we recommend using [TypeScript project references](/docs/4.x/guide/directory-structure/tsconfig) with the new configuration files (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, etc.) for better type safety and performance. This legacy file will be removed in a future version of Nuxt.
+::
+
 ### Benefits of Project References
 
 - **Faster builds**: TypeScript can skip rebuilding unchanged projects
@@ -104,13 +85,9 @@ Each of these files is configured to reference the appropriate dependencies and
 - **Isolated compilation**: Errors in one part of your application don't prevent compilation of other parts
 - **Clearer dependency management**: Each project explicitly declares its dependencies
 
-::note
-The project reference setup is handled automatically by Nuxt. You typically don't need to modify these configurations manually, but understanding how they work can help you troubleshoot type-checking issues.
-::
-
 ### Augmenting Types with Project References
 
-Since the project is divided into **multiple type contexts**, it's important to **augment types within the correct context** to ensure they are properly recognized.
+Since the project is divided into **multiple type contexts**, it's important to **augment types within the correct context** to ensure they're properly recognized. TypeScript will not recognize augmentations placed outside these directories unless they are explicitly included in the appropriate context.
 
 For example, if you want to augment types for the `app` context, the augmentation file should be placed in the `app/` directory.
 
@@ -118,15 +95,15 @@ Similarly:
 - For the `server` context, place the augmentation file in the `server/` directory.
 - For types that are **shared between the app and server**, place the file in the `shared/` directory.
 
-::warning
-Augmenting types outside of these directories will not be recognized by TypeScript.
+::read-more{to="/docs/4.x/guide/going-further/modules#extending-tsconfigjson"}
+Read more about augmenting specific type contexts from **files outside those contexts** in the Module Author Guide.
 ::
 
 ## Strict Checks
 
 TypeScript comes with certain checks to give you more safety and analysis of your program.
 
-[Strict checks](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html#getting-stricter-checks) are enabled by default in Nuxt to give you greater type safety.
+[Strict checks](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html#getting-stricter-checks) are enabled by default in Nuxt when the [`typescript.typeCheck`](/docs/4.x/guide/concepts/typescript#type-checking) option is enabled to give you greater type safety.
 
 If you are currently converting your codebase to TypeScript, you may want to temporarily disable strict checks by setting `strict` to `false` in your `nuxt.config`:
 

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

@@ -653,6 +653,19 @@ export default defineNuxtModule({
 })
 ```
 
+#### Updating Templates
+
+If you need to update your templates/virtual files, you can leverage the `updateTemplates` utility like this:
+
+```ts
+nuxt.hook('builder:watch', (event, path) => {
+  if (path.includes('my-module-feature.config')) {
+    // This will reload the template that you registered
+    updateTemplates({ filter: t => t.filename === 'my-module-feature.mjs' })
+  }
+})
+```
+
 #### Adding Type Declarations
 
 You might also want to add a type declaration to the user's project (for example, to augment a Nuxt interface
@@ -691,19 +704,73 @@ nuxt.hook('prepare:types', ({ references }) => {
 })
 ```
 
-##### Updating Templates
+#### Extending `tsconfig.json`
+
+There are multiple ways to extend the TypeScript configuration of the user's project from your module.
 
-If you need to update your templates/virtual files, you can leverage the `updateTemplates` utility like this :
+The simplest way is to modify the Nuxt configuration directly like this:
 
+<!-- @case-police-ignore tsConfig -->
 ```ts
-nuxt.hook('builder:watch', (event, path) => {
-  if (path.includes('my-module-feature.config')) {
-    // This will reload the template that you registered
-    updateTemplates({ filter: t => t.filename === 'my-module-feature.mjs' })
-  }
+// extend tsconfig.app.json
+nuxt.options.typescript.tsConfig.include ??= []
+nuxt.options.typescript.tsConfig.include.push(resolve('./augments.d.ts'))
+
+// extend tsconfig.shared.json
+nuxt.options.typescript.sharedTsConfig.include ??= []
+nuxt.options.typescript.sharedTsConfig.include.push(resolve('./augments.d.ts'))
+
+// extend tsconfig.node.json
+nuxt.options.typescript.nodeTsConfig.include ??= []
+nuxt.options.typescript.nodeTsConfig.include.push(resolve('./augments.d.ts'))
+
+// extend tsconfig.server.json
+nuxt.options.nitro.typescript ??= {}
+nuxt.options.nitro.typescript.tsConfig ??= {}
+nuxt.options.nitro.typescript.tsConfig.include ??= []
+nuxt.options.nitro.typescript.tsConfig.include.push(resolve('./augments.d.ts'))
+```
+
+Alternatively, you can use the `prepare:types` and `nitro:prepare:types` hooks to extend the TypeScript references for specific type contexts, or modify the TypeScript configuration similar to the example above.
+
+```ts
+nuxt.hook('prepare:types', ({ references, sharedReferences, nodeReferences }) => {
+  // extend app context
+  references.push({ path: resolve('./augments.d.ts') })
+  // extend shared context
+  sharedReferences.push({ path: resolve('./augments.d.ts') })
+  // extend node context
+  nodeReferences.push({ path: resolve('./augments.d.ts') })
+})
+
+nuxt.hook('nitro:prepare:types', ({ references }) => {
+  // extend server context
+  references.push({ path: resolve('./augments.d.ts') })
 })
 ```
 
+::note
+TypeScript references add files to the type context [without being affected by the `exclude` option in `tsconfig.json`](https://www.typescriptlang.org/tsconfig/#exclude).
+::
+
+#### Augmenting Types From Modules
+
+Nuxt automatically includes your module's directories in the appropriate type contexts. To augment types from your module, all you need to do is place the type declaration file in the appropriate directory based on the augmented type context. Alternatively, you can [extend the TypeScript configuration](/docs/4.x/guide/going-further/modules#extending-tsconfigjson) to augment from an arbitrary location.
+
+- `my-module/runtime/` - app type context (except for the `runtime/server` directory)
+- `my-module/runtime/server/` - server type context
+- `my-module/` - node type context (except for the `runtime/` and `runtime/server` directories)
+
+```bash [Directory Structure]
+-| my-module/   # node type context
+---| runtime/   # app type context
+------| augments.app.d.ts
+------| server/ # server type context
+---------| augments.server.d.ts
+---| module.ts
+---| augments.node.d.ts
+```
+
 ### Testing
 
 Testing helps ensuring your module works as expected given various setup. Find in this section how to perform various kinds of tests against your module.
@@ -774,7 +841,7 @@ An example of such a workflow is available on [the module starter](https://githu
 
 Having a playground Nuxt application to test your module when developing it is really useful. [The module starter integrates one for that purpose](/docs/4.x/guide/going-further/modules#how-to-develop).
 
-You can test your module with other Nuxt applications (applications that are not part of your module repository) locally. To do so, you can use [`npm pack`](https://docs.npmjs.com/cli/commands/npm-pack) command, or your package manager equivalent, to create a tarball from your module. Then in your test project, you can add your module to `package.json` packages as: `"my-module": "file:/path/to/tarball.tgz"`.
+You can test your module with other Nuxt applications (applications that are not part of your module repository) locally. To do so, you can use [`npm pack`](https://docs.npmjs.com/cli/commands/npm-pack/) command, or your package manager equivalent, to create a tarball from your module. Then in your test project, you can add your module to `package.json` packages as: `"my-module": "file:/path/to/tarball.tgz"`.
 
 After that, you should be able to reference `my-module` like in any regular project.
 

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

@@ -234,12 +234,12 @@ export type AsyncDataHandler<ResT> = (nuxtApp: NuxtApp, options: { signal: Abort
 
 export function useAsyncData<DataT, DataE> (
   handler: AsyncDataHandler<DataT>,
-  options?: AsyncDataOptions<DataT>
+  options?: AsyncDataOptions<DataT>,
 ): AsyncData<DataT, DataE>
 export function useAsyncData<DataT, DataE> (
   key: MaybeRefOrGetter<string>,
   handler: AsyncDataHandler<DataT>,
-  options?: AsyncDataOptions<DataT>
+  options?: AsyncDataOptions<DataT>,
 ): Promise<AsyncData<DataT, DataE>>
 
 type AsyncDataOptions<DataT> = {

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

@@ -42,7 +42,7 @@ export interface CookieRef<T> extends Ref<T> {}
 
 export function useCookie<T = string | null | undefined> (
   name: string,
-  options?: CookieOptions<T>
+  options?: CookieOptions<T>,
 ): CookieRef<T>
 ```
 

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

@@ -128,7 +128,7 @@ searchQuery.value = 'new search'
 ```ts [Signature]
 export function useFetch<DataT, ErrorT> (
   url: string | Request | Ref<string | Request> | (() => string | Request),
-  options?: UseFetchOptions<DataT>
+  options?: UseFetchOptions<DataT>,
 ): Promise<AsyncData<DataT, ErrorT>>
 
 type UseFetchOptions<DataT> = {

package/3.api/2.composables/use-head-safe.md

@@ -8,28 +8,12 @@ links:
     size: xs
 ---
 
-The `useHeadSafe` composable is a wrapper around the [`useHead`](/docs/4.x/api/composables/use-head) composable that restricts the input to only allow safe values.
-
 ## Usage
 
-You can pass all the same values as [`useHead`](/docs/4.x/api/composables/use-head)
-
-```ts
-useHeadSafe({
-  script: [
-    { id: 'xss-script', innerHTML: 'alert("xss")' },
-  ],
-  meta: [
-    { 'http-equiv': 'refresh', 'content': '0;javascript:alert(1)' },
-  ],
-})
-// Will safely generate
-// <script id="xss-script"></script>
-// <meta content="0;javascript:alert(1)">
-```
+The `useHeadSafe` composable is a wrapper around the [`useHead`](/docs/4.x/api/composables/use-head) composable that restricts the input to only allow safe values. This is the recommended way to manage head data when working with user input, as it prevents XSS attacks by sanitizing potentially dangerous attributes.
 
-::read-more{to="https://unhead.unjs.io/docs/typescript/head/api/composables/use-head-safe" target="_blank"}
-Read more on the `Unhead` documentation.
+::warning
+When using `useHeadSafe`, potentially dangerous attributes like `innerHTML` in scripts or `http-equiv` in meta tags are automatically stripped out to prevent XSS attacks. Use this composable whenever you're working with user-generated content.
 ::
 
 ## Type
@@ -38,7 +22,9 @@ Read more on the `Unhead` documentation.
 export function useHeadSafe (input: MaybeComputedRef<HeadSafe>): void
 ```
 
-The list of allowed values is:
+### Allowed Attributes
+
+The following attributes are whitelisted for each head element type:
 
 ```ts
 const WhitelistAttributes = {
@@ -53,3 +39,34 @@ const WhitelistAttributes = {
 ```
 
 See [@unhead/vue](https://github.com/unjs/unhead/blob/main/packages/vue/src/types/safeSchema.ts) for more detailed types.
+
+## Parameters
+
+`input`: A `MaybeComputedRef<HeadSafe>` object containing head data. You can pass all the same values as [`useHead`](/docs/4.x/api/composables/use-head), but only safe attributes will be rendered.
+
+## Return Values
+
+This composable does not return any value.
+
+## Example
+
+```vue [app/pages/user-profile.vue]
+<script setup lang="ts">
+// User-generated content that might contain malicious code
+const userBio = ref('<script>alert("xss")<' + '/script>')
+
+useHeadSafe({
+  title: `User Profile`,
+  meta: [
+    {
+      name: 'description',
+      content: userBio.value, // Safely sanitized
+    },
+  ],
+})
+</script>
+```
+
+::read-more{to="https://unhead.unjs.io/docs/typescript/head/api/composables/use-head-safe" target="_blank"}
+Read more on the `Unhead` documentation.
+::

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

@@ -8,19 +8,38 @@ links:
     size: xs
 ---
 
-The [`useHead`](/docs/4.x/api/composables/use-head) composable function allows you to manage your head tags in a programmatic and reactive way, powered by [Unhead](https://unhead.unjs.io). If the data comes from a user or other untrusted source, we recommend you check out [`useHeadSafe`](/docs/4.x/api/composables/use-head-safe).
+## Usage
 
-:read-more{to="/docs/4.x/getting-started/seo-meta"}
+The `useHead` composable allows you to manage your head tags in a programmatic and reactive way, powered by [Unhead](https://unhead.unjs.io). It lets you customize the meta tags, links, scripts, and other elements in the `<head>` section of your HTML document.
+
+```vue [app/app.vue]
+<script setup lang="ts">
+useHead({
+  title: 'My App',
+  meta: [
+    { name: 'description', content: 'My amazing site.' },
+  ],
+  bodyAttrs: {
+    class: 'test',
+  },
+  script: [{ innerHTML: 'console.log(\'Hello world\')' }],
+})
+</script>
+```
+
+::warning
+If the data comes from a user or other untrusted source, we recommend you check out [`useHeadSafe`](/docs/4.x/api/composables/use-head-safe).
+::
+
+::note
+The properties of `useHead` can be dynamic, accepting `ref`, `computed` and `reactive` properties. The `meta` parameter can also accept a function returning an object to make the entire object reactive.
+::
 
 ## Type
 
 ```ts [Signature]
 export function useHead (meta: MaybeComputedRef<MetaObject>): void
-```
 
-Below are the non-reactive types for [`useHead`](/docs/4.x/api/composables/use-head) .
-
-```ts
 interface MetaObject {
   title?: string
   titleTemplate?: string | ((title?: string) => string)
@@ -35,35 +54,116 @@ interface MetaObject {
 }
 ```
 
-See [@unhead/vue](https://github.com/unjs/unhead/blob/main/packages/vue/src/types/schema.ts) for more detailed types.
+See [@unhead/schema](https://github.com/unjs/unhead/blob/main/packages/vue/src/types/schema.ts) for more detailed types.
 
-::note
-The properties of `useHead` can be dynamic, accepting `ref`, `computed` and `reactive` properties. `meta` parameter can also accept a function returning an object to make the entire object reactive.
-::
+## Parameters
+
+`meta`: An object accepting head metadata properties to customize the page's `<head>` section. All properties support reactive values (`ref`, `computed`, `reactive`) or can be a function returning the metadata object.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `title` | `string` | Sets the page title. |
+| `titleTemplate` | `string \| ((title?: string) => string)` | Configures a dynamic template to customize the page title. Can be a string with `%s` placeholder or a function. |
+| `base` | `Base` | Sets the `<base>` tag for the document. |
+| `link` | `Link[]` | Array of link objects. Each element is mapped to a `<link>` tag, where object properties correspond to HTML attributes. |
+| `meta` | `Meta[]` | Array of meta objects. Each element is mapped to a `<meta>` tag, where object properties correspond to HTML attributes. |
+| `style` | `Style[]` | Array of style objects. Each element is mapped to a `<style>` tag, where object properties correspond to HTML attributes. |
+| `script` | `Script[]` | Array of script objects. Each element is mapped to a `<script>` tag, where object properties correspond to HTML attributes. |
+| `noscript` | `Noscript[]` | Array of noscript objects. Each element is mapped to a `<noscript>` tag, where object properties correspond to HTML attributes. |
+| `htmlAttrs` | `HtmlAttributes` | Sets attributes of the `<html>` tag. Each object property is mapped to the corresponding attribute. |
+| `bodyAttrs` | `BodyAttributes` | Sets attributes of the `<body>` tag. Each object property is mapped to the corresponding attribute. |
+
+## Return Values
+
+This composable does not return any value. It registers the head metadata with Unhead, which manages the actual DOM updates.
+
+## Examples
+
+### Basic Meta Tags
 
-## Params
-
-### `meta`
-
-**Type**: `MetaObject`
-
-An object accepting the following head metadata:
-
-- `meta`: Each element in the array is mapped to a newly-created `<meta>` tag, where object properties are mapped to the corresponding attributes.
-  - **Type**: `Array<Record<string, any>>`
-- `link`: Each element in the array is mapped to a newly-created `<link>` tag, where object properties are mapped to the corresponding attributes.
-  - **Type**: `Array<Record<string, any>>`
-- `style`: Each element in the array is mapped to a newly-created `<style>` tag, where object properties are mapped to the corresponding attributes.
-  - **Type**: `Array<Record<string, any>>`
-- `script`: Each element in the array is mapped to a newly-created `<script>` tag, where object properties are mapped to the corresponding attributes.
-  - **Type**: `Array<Record<string, any>>`
-- `noscript`: Each element in the array is mapped to a newly-created `<noscript>` tag, where object properties are mapped to the corresponding attributes.
-  - **Type**: `Array<Record<string, any>>`
-- `titleTemplate`: Configures dynamic template to customize the page title on an individual page.
-  - **Type**: `string` | `((title: string) => string)`
-- `title`: Sets static page title on an individual page.
-  - **Type**: `string`
-- `bodyAttrs`: Sets attributes of the `<body>` tag. Each object property is mapped to the corresponding attribute.
-  - **Type**: `Record<string, any>`
-- `htmlAttrs`: Sets attributes of the `<html>` tag. Each object property is mapped to the corresponding attribute.
-  - **Type**: `Record<string, any>`
+```vue [app/pages/about.vue]
+<script setup lang="ts">
+useHead({
+  title: 'About Us',
+  meta: [
+    { name: 'description', content: 'Learn more about our company' },
+    { property: 'og:title', content: 'About Us' },
+    { property: 'og:description', content: 'Learn more about our company' },
+  ],
+})
+</script>
+```
+
+### Reactive Meta Tags
+
+```vue [app/pages/profile.vue]
+<script setup lang="ts">
+const profile = ref({ name: 'John Doe' })
+
+useHead({
+  title: computed(() => profile.value.name),
+  meta: [
+    {
+      name: 'description',
+      content: computed(() => `Profile page for ${profile.value.name}`),
+    },
+  ],
+})
+</script>
+```
+
+### Using a Function for Full Reactivity
+
+```vue [app/pages/dynamic.vue]
+<script setup lang="ts">
+const count = ref(0)
+
+useHead(() => ({
+  title: `Count: ${count.value}`,
+  meta: [
+    { name: 'description', content: `Current count is ${count.value}` },
+  ],
+}))
+</script>
+```
+
+### Adding External Scripts and Styles
+
+```vue [app/pages/external.vue]
+<script setup lang="ts">
+useHead({
+  link: [
+    {
+      rel: 'stylesheet',
+      href: 'https://cdn.example.com/styles.css',
+    },
+  ],
+  script: [
+    {
+      src: 'https://cdn.example.com/script.js',
+      async: true,
+    },
+  ],
+})
+</script>
+```
+
+### Body and HTML Attributes
+
+```vue [app/pages/themed.vue]
+<script setup lang="ts">
+const isDark = ref(true)
+
+useHead({
+  htmlAttrs: {
+    lang: 'en',
+    class: computed(() => isDark.value ? 'dark' : 'light'),
+  },
+  bodyAttrs: {
+    class: 'themed-page',
+  },
+})
+</script>
+```
+
+:read-more{to="/docs/4.x/getting-started/seo-meta"}

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

@@ -8,6 +8,8 @@ links:
     size: xs
 ---
 
+`useHydration` is a built-in composable that provides a way to set data on the server side every time a new HTTP request is made and receive that data on the client side. This way `useHydration` allows you to take full control of the hydration cycle.
+
 ::note
 This is an advanced composable, primarily designed for use within plugins, mostly used by Nuxt modules.
 ::
@@ -16,14 +18,24 @@ This is an advanced composable, primarily designed for use within plugins, mostl
 `useHydration` is designed to **ensure state synchronization and restoration during SSR**. If you need to create a globally reactive state that is SSR-friendly in Nuxt, [`useState`](/docs/4.x/api/composables/use-state) is the recommended choice.
 ::
 
-`useHydration` is a built-in composable that provides a way to set data on the server side every time a new HTTP request is made and receive that data on the client side. This way `useHydration` allows you to take full control of the hydration cycle.
+## Usage
 
 The data returned from the `get` function on the server is stored in `nuxtApp.payload` under the unique key provided as the first parameter to `useHydration`. During hydration, this data is then retrieved on the client, preventing redundant computations or API calls.
 
-## Usage
-
 ::code-group
 
+```ts [With useHydration]
+export default defineNuxtPlugin((nuxtApp) => {
+  const myStore = new MyStore()
+
+  useHydration(
+    'myStoreState',
+    () => myStore.getState(),
+    data => myStore.setState(data),
+  )
+})
+```
+
 ```ts [Without useHydration]
 export default defineNuxtPlugin((nuxtApp) => {
   const myStore = new MyStore()
@@ -41,18 +53,6 @@ export default defineNuxtPlugin((nuxtApp) => {
   }
 })
 ```
-
-```ts [With useHydration]
-export default defineNuxtPlugin((nuxtApp) => {
-  const myStore = new MyStore()
-
-  useHydration(
-    'myStoreState',
-    () => myStore.getState(),
-    data => myStore.setState(data),
-  )
-})
-```
 ::
 
 ## Type
@@ -63,6 +63,12 @@ export function useHydration<T> (key: string, get: () => T, set: (value: T) => v
 
 ## Parameters
 
-- `key`: A unique key that identifies the data in your Nuxt application.
-- `get`: A function executed **only on the server** (called when SSR rendering is done) to set the initial value.
-- `set`: A function executed **only on the client** (called when initial vue instance is created) to receive the data.
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `key` | `string` | A unique key that identifies the data in your Nuxt application. |
+| `get` | `() => T` | A function executed **only on the server** (called when SSR rendering is done) to set the initial value. |
+| `set` | `(value: T) => void` | A function executed **only on the client** (called when initial Vue instance is created) to receive the data. |
+
+## Return Values
+
+This composable does not return any value.

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

@@ -8,15 +8,68 @@ links:
     size: xs
 ---
 
-## Description
-
-By default, [`useAsyncData`](/docs/4.x/api/composables/use-async-data) blocks navigation until its async handler is resolved. `useLazyAsyncData` provides a wrapper around [`useAsyncData`](/docs/4.x/api/composables/use-async-data) that triggers navigation before the handler is resolved by setting the `lazy` option to `true`.
+`useLazyAsyncData` provides a wrapper around [`useAsyncData`](/docs/4.x/api/composables/use-async-data) that triggers navigation before the handler is resolved by setting the `lazy` option to `true`.
 
 ::note
-`useLazyAsyncData` has the same signature as [`useAsyncData`](/docs/4.x/api/composables/use-async-data).
+By default, [`useAsyncData`](/docs/4.x/api/composables/use-async-data) blocks navigation until its async handler is resolved. `useLazyAsyncData` allows navigation to occur immediately while data fetching continues in the background.
 ::
 
-:read-more{to="/docs/4.x/api/composables/use-async-data"}
+## Usage
+
+```vue [app/pages/index.vue]
+<script setup lang="ts">
+const { status, data: posts } = await useLazyAsyncData('posts', () => $fetch('/api/posts'))
+</script>
+
+<template>
+  <div>
+    <div v-if="status === 'pending'">
+      Loading...
+    </div>
+    <div v-else-if="status === 'error'">
+      Error loading posts
+    </div>
+    <div v-else>
+      {{ posts }}
+    </div>
+  </div>
+</template>
+```
+
+When using `useLazyAsyncData`, navigation will occur before fetching is complete. This means you must handle `pending` and `error` states directly within your component's template.
+
+::warning
+`useLazyAsyncData` is a reserved function name transformed by the compiler, so you should not name your own function `useLazyAsyncData`.
+::
+
+## Type
+
+```ts [Signature]
+export function useLazyAsyncData<DataT, ErrorT> (
+  handler: (ctx?: NuxtApp) => Promise<DataT>,
+  options?: AsyncDataOptions<DataT>,
+): AsyncData<DataT, ErrorT>
+
+export function useLazyAsyncData<DataT, ErrorT> (
+  key: string,
+  handler: (ctx?: NuxtApp) => Promise<DataT>,
+  options?: AsyncDataOptions<DataT>,
+): AsyncData<DataT, ErrorT>
+```
+
+`useLazyAsyncData` has the same signature as [`useAsyncData`](/docs/4.x/api/composables/use-async-data).
+
+## Parameters
+
+`useLazyAsyncData` accepts the same parameters as [`useAsyncData`](/docs/4.x/api/composables/use-async-data), with the `lazy` option automatically set to `true`.
+
+:read-more{to="/docs/4.x/api/composables/use-async-data#parameters"}
+
+## Return Values
+
+`useLazyAsyncData` returns the same values as [`useAsyncData`](/docs/4.x/api/composables/use-async-data).
+
+:read-more{to="/docs/4.x/api/composables/use-async-data#return-values"}
 
 ## Example
 
@@ -40,8 +93,4 @@ watch(count, (newCount) => {
 </template>
 ```
 
-::warning
-`useLazyAsyncData` is a reserved function name transformed by the compiler, so you should not name your own function `useLazyAsyncData`.
-::
-
 :read-more{to="/docs/4.x/getting-started/data-fetching"}

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

@@ -8,21 +8,81 @@ links:
     size: xs
 ---
 
-## Description
+`useLazyFetch` provides a wrapper around [`useFetch`](/docs/4.x/api/composables/use-fetch) that triggers navigation before the handler is resolved by setting the `lazy` option to `true`.
 
-By default, [`useFetch`](/docs/4.x/api/composables/use-fetch) blocks navigation until its async handler is resolved. `useLazyFetch` provides a wrapper around [`useFetch`](/docs/4.x/api/composables/use-fetch) that triggers navigation before the handler is resolved by setting the `lazy` option to `true`.
+## Usage
+
+By default, [`useFetch`](/docs/4.x/api/composables/use-fetch) blocks navigation until its async handler is resolved. `useLazyFetch` allows navigation to proceed immediately, with data being fetched in the background.
+
+```vue [app/pages/index.vue]
+<script setup lang="ts">
+const { status, data: posts } = await useLazyFetch('/api/posts')
+</script>
+
+<template>
+  <div v-if="status === 'pending'">
+    Loading ...
+  </div>
+  <div v-else>
+    <div v-for="post in posts">
+      <!-- do something -->
+    </div>
+  </div>
+</template>
+```
 
 ::note
 `useLazyFetch` has the same signature as [`useFetch`](/docs/4.x/api/composables/use-fetch).
 ::
 
+::warning
+Awaiting `useLazyFetch` only ensures the call is initialized. On client-side navigation, data may not be immediately available, and you must handle the `pending` state in your component's template.
+::
+
+::warning
+`useLazyFetch` is a reserved function name transformed by the compiler, so you should not name your own function `useLazyFetch`.
+::
+
+## Type
+
+```ts [Signature]
+export function useLazyFetch<DataT, ErrorT> (
+  url: string | Request | Ref<string | Request> | (() => string | Request),
+  options?: UseFetchOptions<DataT>,
+): Promise<AsyncData<DataT, ErrorT>>
+```
+
 ::note
-Awaiting `useLazyFetch` in this mode only ensures the call is initialized. On client-side navigation, data may not be immediately available, and you should make sure to handle the pending state in your app.
+`useLazyFetch` is equivalent to `useFetch` with `lazy: true` option set. See [`useFetch`](/docs/4.x/api/composables/use-fetch) for full type definitions.
 ::
 
-:read-more{to="/docs/4.x/api/composables/use-fetch"}
+## Parameters
+
+`useLazyFetch` accepts the same parameters as [`useFetch`](/docs/4.x/api/composables/use-fetch):
+
+- `URL` (`string | Request | Ref<string | Request> | () => string | Request`): The URL or request to fetch.
+- `options` (object): Same as [`useFetch` options](/docs/4.x/api/composables/use-fetch#parameters), with `lazy` automatically set to `true`.
+
+:read-more{to="/docs/4.x/api/composables/use-fetch#parameters"}
 
-## Example
+## Return Values
+
+Returns the same `AsyncData` object as [`useFetch`](/docs/4.x/api/composables/use-fetch):
+
+| Name | Type | Description |
+| --- | --- |--- |
+| `data` | `Ref<DataT \| undefined>` | The result of the asynchronous fetch. |
+| `refresh` | `(opts?: AsyncDataExecuteOptions) => Promise<void>` | Function to manually refresh the data. |
+| `execute` | `(opts?: AsyncDataExecuteOptions) => Promise<void>` | Alias for `refresh`. |
+| `error` | `Ref<ErrorT \| undefined>` | Error object if the data fetching failed. |
+| `status` | `Ref<'idle' \| 'pending' \| 'success' \| 'error'>` | Status of the data request. |
+| `clear` | `() => void` | Resets `data` to `undefined`, `error` to `undefined`, sets `status` to `idle`, and cancels any pending requests. |
+
+:read-more{to="/docs/4.x/api/composables/use-fetch#return-values"}
+
+## Examples
+
+### Handling Pending State
 
 ```vue [app/pages/index.vue]
 <script setup lang="ts">
@@ -48,8 +108,4 @@ watch(posts, (newPosts) => {
 </template>
 ```
 
-::note
-`useLazyFetch` is a reserved function name transformed by the compiler, so you should not name your own function `useLazyFetch`.
-::
-
 :read-more{to="/docs/4.x/getting-started/data-fetching"}

package/3.api/2.composables/use-runtime-hook.md

@@ -15,7 +15,7 @@ This composable is available in Nuxt v3.14+.
 ```ts [signature]
 function useRuntimeHook<THookName extends keyof RuntimeNuxtHooks> (
   name: THookName,
-  fn: RuntimeNuxtHooks[THookName] extends HookCallback ? RuntimeNuxtHooks[THookName] : never
+  fn: RuntimeNuxtHooks[THookName] extends HookCallback ? RuntimeNuxtHooks[THookName] : never,
 ): void
 ```
 

package/3.api/3.utils/navigate-to.md

@@ -119,7 +119,7 @@ await navigateTo('https://nuxt.com', {
 ```ts [Signature]
 export function navigateTo (
   to: RouteLocationRaw | undefined | null,
-  options?: NavigateToOptions
+  options?: NavigateToOptions,
 ): Promise<void | NavigationFailure | false> | false | void | RouteLocationRaw
 
 interface NavigateToOptions {

package/3.api/5.kit/1.modules.md

@@ -47,7 +47,7 @@ export function defineNuxtModule<TOptions extends ModuleOptions> (
 
 export function defineNuxtModule<TOptions extends ModuleOptions> (): {
   with: <TOptionsDefaults extends Partial<TOptions>> (
-    definition: ModuleDefinition<TOptions, TOptionsDefaults, true> | NuxtModule<TOptions, TOptionsDefaults, true>
+    definition: ModuleDefinition<TOptions, TOptionsDefaults, true> | NuxtModule<TOptions, TOptionsDefaults, true>,
   ) => NuxtModule<TOptions, TOptionsDefaults, true>
 }
 ```

package/3.api/5.kit/2.programmatic.md

@@ -8,7 +8,7 @@ links:
     size: xs
 ---
 
-Programmatic usage can be helpful when you want to use Nuxt programmatically, for example, when building a [CLI tool](https://github.com/nuxt/cli) or [test utils](https://github.com/nuxt/nuxt/tree/main/packages/test-utils).
+Programmatic usage can be helpful when you want to use Nuxt programmatically, for example, when building a [CLI tool](https://github.com/nuxt/cli) or [test utils](https://github.com/nuxt/test-utils).
 
 ## `loadNuxt`
 
@@ -31,7 +31,7 @@ function loadNuxt (loadOptions?: LoadNuxtOptions): Promise<Nuxt>
 
 ## `buildNuxt`
 
-Build Nuxt programmatically. It will invoke the builder (currently [@nuxt/vite-builder](https://github.com/nuxt/nuxt/tree/main/packages/vite) or [@nuxt/webpack-builder](https://github.com/nuxt/nuxt/tree/main/packages/webpack)) to bundle the application.
+Build Nuxt programmatically. It will invoke the builder (currently [@nuxt/vite-builder](https://github.com/nuxt/nuxt/blob/main/packages/vite) or [@nuxt/webpack-builder](https://github.com/nuxt/nuxt/blob/main/packages/webpack)) to bundle the application.
 
 ### Type
 

package/3.api/6.nuxt-config.md

@@ -2133,7 +2133,7 @@ See [css-loader](https://github.com/webpack/css-loader) for available options.
 }
 ```
 
-**See**: [esbuild loader](https://github.com/esbuild-kit/esbuild-loader)
+**See**: [esbuild loader](https://github.com/privatenumber/esbuild-loader)
 
 #### `file`
 

package/5.community/3.reporting-bugs.md

@@ -39,7 +39,7 @@ If your issue concerns Vue or Vite, please try to reproduce it first with the Vu
 
 ::card-group
   :card{title="Vue SSR on StackBlitz" icon="i-simple-icons-stackblitz" to="https://stackblitz.com/github/nuxt-contrib/vue3-ssr-starter/tree/main?terminal=dev" target="_blank"}
-  :card{title="Vue SSR on CodeSandbox" icon="i-simple-icons-codesandbox" to="https://codesandbox.io/s/github/nuxt-contrib/vue3-ssr-starter/main" target="_blank"}
+  :card{title="Vue SSR on CodeSandbox" icon="i-simple-icons-codesandbox" to="https://codesandbox.io/p/sandbox/github/nuxt-contrib/vue3-ssr-starter/main" target="_blank"}
   :card{title="Vue SSR Template on GitHub" icon="i-simple-icons-github" to="https://github.com/nuxt-contrib/vue3-ssr-starter/generate" target="_blank"}
 ::
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "4.2.1-29370805.6a102676",
+  "version": "4.2.1-29370820.95518afa",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",