@nuxt/docs 3.19.3 → 3.20.0

package/1.getting-started/02.installation.md

@@ -28,7 +28,7 @@ Or follow the steps below to set up a new Nuxt project on your computer.
 ::note
   ::details
   :summary[Additional notes for an optimal setup:]
-  - **Node.js**: Make sure to use an even numbered version (18, 20, etc)
+  - **Node.js**: Make sure to use an even numbered version (20, 22, etc.)
   - **Nuxtr**: Install the community-developed [Nuxtr extension](https://marketplace.visualstudio.com/items?itemName=Nuxtr.nuxtr-vscode)
   - **WSL**: If you are using Windows and experience slow HMR, you may want to try using [WSL (Windows Subsystem for Linux)](https://docs.microsoft.com/en-us/windows/wsl/install) which may solve some performance issues.
   - **Windows slow DNS resolution** - instead of using `localhost:3000` for local dev server on Windows, use `127.0.0.1` for much faster loading experience on browsers.

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

@@ -120,19 +120,23 @@ You can run all the codemods mentioned in this guide using the following `codemo
 ::code-group
 
 ```bash [npm]
-npx codemod@latest nuxt/4/migration-recipe
+# Using pinned version due to https://github.com/codemod-com/codemod/issues/1710
+npx codemod@0.18.7 nuxt/4/migration-recipe
 ```
 
 ```bash [yarn]
-yarn dlx codemod@latest nuxt/4/migration-recipe
+# Using pinned version due to https://github.com/codemod-com/codemod/issues/1710
+yarn dlx codemod@0.18.7 nuxt/4/migration-recipe
 ```
 
 ```bash [pnpm]
-pnpm dlx codemod@latest nuxt/4/migration-recipe
+# Using pinned version due to https://github.com/codemod-com/codemod/issues/1710
+pnpm dlx codemod@0.18.7 nuxt/4/migration-recipe
 ```
 
 ```bash [bun]
-bun x codemod@latest nuxt/4/migration-recipe
+# Using pinned version due to https://github.com/codemod-com/codemod/issues/1710
+bun x codemod@0.18.7 nuxt/4/migration-recipe
 ```
 
 ::

package/2.guide/2.concepts/7.esm.md

@@ -50,6 +50,10 @@ When adding modules to your package, things were a little different. A sample li
 
 So in Nuxt 2, the bundler (webpack) would pull in the CJS file ('main') for the server build and use the ESM file ('module') for the client build.
 
+::note
+The `module` field is a convention used by bundlers like webpack and Rollup, but is not recognized by Node.js itself. Node.js only uses the [`exports`](https://nodejs.org/api/packages.html#exports) and [`main`](https://nodejs.org/api/packages.html#main) fields for module resolution.
+::
+
 However, in recent Node.js LTS releases, it is now possible to [use native ESM module](https://nodejs.org/api/esm.html) within Node.js. That means that Node.js itself can process JavaScript using ESM syntax, although it doesn't do it by default. The two most common ways to enable ESM syntax are:
 
 - set `"type": "module"` within your `package.json` and keep using `.js` extension
@@ -59,7 +63,7 @@ This is what we do for Nuxt Nitro; we output a `.output/server/index.mjs` file.
 
 ### What Are Valid Imports in a Node.js Context?
 
-When you `import` a module rather than `require` it, Node.js resolves it differently. For example, when you import `sample-library`, Node.js will look not for the `main` but for the `exports` or `module` entry in that library's `package.json`.
+When you `import` a module rather than `require` it, Node.js resolves it differently. For example, when you import `sample-library`, Node.js will look for the `exports` entry in that library's `package.json`, or fall back to the `main` entry if `exports` is not defined.
 
 This is also true of dynamic imports, like `const b = await import('sample-library')`.
 

package/2.guide/3.going-further/1.experimental-features.md

@@ -71,6 +71,44 @@ export default defineNuxtConfig({
 })
 ```
 
+## extractAsyncDataHandlers
+
+Extracts handler functions from `useAsyncData` and `useLazyAsyncData` calls into separate chunks for improved code splitting and caching efficiency.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    extractAsyncDataHandlers: true,
+  },
+})
+```
+
+This feature transforms inline handler functions into dynamically imported chunks:
+
+```vue
+<!-- Before -->
+<script setup>
+const { data } = await useAsyncData('user', async () => {
+  return await $fetch('/api/user')
+})
+</script>
+```
+
+```vue
+<!-- After transformation -->
+<script setup>
+const { data } = await useAsyncData('user', () =>
+  import('/generated-chunk.js').then(r => r.default()),
+)
+</script>
+```
+
+The benefit of this transformation is that we can split out data fetching logic &mdash; while still allowing the code to be loaded if required.
+
+::important
+This feature is only recommended for **static builds** with payload extraction, and where data does not need to be re-fetched at runtime.
+::
+
 ## emitRouteChunkError
 
 Emits `app:chunkError` hook when there is an error loading vite/webpack chunks. Default behavior is to perform a reload of the new route on navigation to a new route when a chunk fails to load.
@@ -721,3 +759,53 @@ export default defineNuxtConfig({
   },
 })
 ```
+
+## typescriptPlugin
+
+Enable enhanced TypeScript developer experience with the `@dxup/nuxt` module.
+
+This experimental plugin provides improved TypeScript integration and development tooling for better DX when working with TypeScript in Nuxt applications.
+
+This flag is disabled by default, but you can enable this feature:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    typescriptPlugin: true,
+  },
+})
+```
+
+::important
+To use this feature, you need to:
+- Have `typescript` installed as a dependency
+- Configure VS Code to use your workspace TypeScript version (see [VS Code documentation](https://code.visualstudio.com/docs/typescript/typescript-compiling#_using-the-workspace-version-of-typescript))
+::
+
+::read-more{icon="i-simple-icons-github" to="https://github.com/KazariEX/dxup" target="_blank"}
+Learn more about **@dxup/nuxt**.
+::
+
+## viteEnvironmentApi
+
+Enable Vite 6's new [Environment API](https://vite.dev/guide/api-environment) for improved build configuration and plugin architecture.
+
+When you set `future.compatibilityVersion` to `5`, this feature is enabled by default. You can also enable it explicitly for testing:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    viteEnvironmentApi: true,
+  },
+})
+```
+
+The Vite Environment API provides better consistency between development and production builds, more granular control over environment-specific configuration, and improved performance.
+
+::important
+Enabling this feature changes how Vite plugins are registered and configured. See the [Vite Environment API migration guide](/docs/4.x/getting-started/upgrade#migration-to-vite-environment-api) for details on updating your plugins.
+::
+
+::read-more{to="https://vite.dev/guide/api-environment" target="_blank"}
+Learn more about Vite's Environment API.
+::

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

@@ -501,35 +501,51 @@ export default defineNuxtModule({
 
 #### Using Other Modules in Your Module
 
-If your module depends on other modules, you can add them by using Nuxt Kit's `installModule` utility. For example, if you wanted to use Nuxt Tailwind in your module, you could add it as below:
+If your module depends on other modules, you can specify them using the `moduleDependencies` option. This provides a more robust way to handle module dependencies with version constraints and configuration merging:
 
 ```ts
-import { createResolver, defineNuxtModule, installModule } from '@nuxt/kit'
-
-export default defineNuxtModule<ModuleOptions>({
-  async setup (options, nuxt) {
-    const resolver = createResolver(import.meta.url)
+import { createResolver, defineNuxtModule } from '@nuxt/kit'
 
-    // We can inject our CSS file which includes Tailwind's directives
-    nuxt.options.css.push(resolver.resolve('./runtime/assets/styles.css'))
+const resolver = createResolver(import.meta.url)
 
-    await installModule('@nuxtjs/tailwindcss', {
-      // module configuration
-      exposeConfig: true,
-      config: {
-        darkMode: 'class',
-        content: {
-          files: [
-            resolver.resolve('./runtime/components/**/*.{vue,mjs,ts}'),
-            resolver.resolve('./runtime/*.{mjs,js,ts}'),
-          ],
+export default defineNuxtModule<ModuleOptions>({
+  meta: {
+    name: 'my-module',
+  },
+  moduleDependencies: {
+    '@nuxtjs/tailwindcss': {
+      // You can specify a version constraint for the module
+      version: '>=6',
+      // Any configuration that should override `nuxt.options`
+      overrides: {
+        exposeConfig: true,
+      },
+      // Any configuration that should be set. It will override module defaults but
+      // will not override any configuration set in `nuxt.options`
+      defaults: {
+        config: {
+          darkMode: 'class',
+          content: {
+            files: [
+              resolver.resolve('./runtime/components/**/*.{vue,mjs,ts}'),
+              resolver.resolve('./runtime/*.{mjs,js,ts}'),
+            ],
+          },
         },
       },
-    })
+    },
+  },
+  setup (options, nuxt) {
+    // We can inject our CSS file which includes Tailwind's directives
+    nuxt.options.css.push(resolver.resolve('./runtime/assets/styles.css'))
   },
 })
 ```
 
+::callout{type="info"}
+The `moduleDependencies` option replaces the deprecated `installModule` function and ensures proper setup order and configuration merging.
+::
+
 #### Using Hooks
 
 [Lifecycle hooks](/docs/3.x/guide/going-further/hooks) allow you to expand almost every aspect of Nuxt. Modules can hook to them programmatically or through the `hooks` map in their definition.

package/2.guide/3.going-further/7.layers.md

@@ -234,22 +234,30 @@ export default defineNuxtConfig({
 
 ## Multi-Layer Support for Nuxt Modules
 
-You can use the internal array `nuxt.options._layers` to support custom multi-layer handling for your modules.
+You can use the [`getLayerDirectories`](/docs/api/kit/layers#getlayerdirectories) utility from Nuxt Kit to support custom multi-layer handling for your modules.
 
 ```ts [modules/my-module.ts]
+import { defineNuxtModule, getLayerDirectories } from 'nuxt/kit'
+
 export default defineNuxtModule({
   setup (_options, nuxt) {
-    for (const layer of nuxt.options._layers) {
-      // You can check for a custom directory existence to extend for each layer
-      console.log('Custom extension for', layer.cwd, layer.config)
+    const layerDirs = getLayerDirectories()
+
+    for (const [index, layer] of layerDirs.entries()) {
+      console.log(`Layer ${index}:`)
+      console.log(`  Root: ${layer.root}`)
+      console.log(`  App: ${layer.app}`)
+      console.log(`  Server: ${layer.server}`)
+      console.log(`  Pages: ${layer.appPages}`)
+      // ... other directories
     }
   },
 })
 ```
 
 **Notes:**
-- Earlier items in the `_layers` array have higher priority and override later ones
-- The user's project is the first item in the `_layers` array
+- Earlier items in the array have higher priority and override later ones
+- The user's project is the first item in the array
 
 ## Going Deeper
 

package/2.guide/4.recipes/2.vite-plugin.md

@@ -63,3 +63,44 @@ import config from '~/data/hello.yaml'
 ```
 
 ::
+
+## Using Vite Plugins in Nuxt Modules
+
+If you're developing a Nuxt module and need to add Vite plugins, you should use the [`addVitePlugin`](/docs/4.x/api/kit/builder#addviteplugin) utility:
+
+```ts [modules/my-module.ts]
+import { addVitePlugin, defineNuxtModule } from '@nuxt/kit'
+import yaml from '@rollup/plugin-yaml'
+
+export default defineNuxtModule({
+  setup () {
+    addVitePlugin(yaml())
+  },
+})
+```
+
+For environment-specific plugins in Nuxt 5+, use the `applyToEnvironment()` method:
+
+```ts [modules/my-module.ts]
+import { addVitePlugin, defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup () {
+    addVitePlugin(() => ({
+      name: 'my-client-plugin',
+      applyToEnvironment (environment) {
+        return environment.name === 'client'
+      },
+      // Plugin configuration
+    }))
+  },
+})
+```
+
+::important
+If you're writing code that needs to access resolved Vite configuration, you should use the `config` and `configResolved` hooks _within_ your Vite plugin, rather than using Nuxt's `vite:extend`, `vite:extendConfig` and `vite:configResolved`.
+::
+
+::read-more{to="/docs/4.x/api/kit/builder#addviteplugin"}
+Read more about `addVitePlugin` in the Nuxt Kit documentation.
+::

package/3.api/1.components/13.nuxt-time.md

@@ -104,13 +104,17 @@ Enables relative time formatting using the Intl.RelativeTimeFormat API:
 
 When `relative` is set to `true`, the component also accepts properties from [Intl.RelativeTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat):
 
+::warning
+Due to `style` being a reserved prop, `relativeStyle` prop is used instead.
+::
+
 ```vue
 <template>
   <NuxtTime
     :datetime="Date.now() - 3 * 24 * 60 * 60 * 1000"
     relative
     numeric="auto"
-    style="long"
+    relative-style="long"
   />
 </template>
 ```

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

@@ -102,6 +102,7 @@ The `handler` function should be **side-effect free** to ensure predictable beha
   - `dedupe`: avoid fetching same key more than once at a time (defaults to `cancel`). Possible options:
     - `cancel` - cancels existing requests when a new one is made
     - `defer` - does not make new requests at all if there is a pending request
+  - `timeout` - a number in milliseconds to wait before timing out the request (defaults to `undefined`, which means no timeout)
 
 ::note
 Under the hood, `lazy: false` uses `<Suspense>` to block the loading of the route before the data has been fetched. Consider using `lazy: true` and implementing a loading state instead for a snappier user experience.
@@ -170,12 +171,12 @@ If you have not fetched data on the server (for example, with `server: false`),
 
 ```ts [Signature]
 export function useAsyncData<DataT, DataE> (
-  handler: (nuxtApp?: NuxtApp) => Promise<DataT>,
+  handler: (nuxtApp: NuxtApp, options: { signal: AbortSignal }) => Promise<DataT>,
   options?: AsyncDataOptions<DataT>
 ): AsyncData<DataT, DataE>
 export function useAsyncData<DataT, DataE> (
   key: MaybeRefOrGetter<string>,
-  handler: (nuxtApp?: NuxtApp) => Promise<DataT>,
+  handler: (nuxtApp: NuxtApp, options: { signal: AbortSignal }) => Promise<DataT>,
   options?: AsyncDataOptions<DataT>
 ): Promise<AsyncData<DataT, DataE>>
 
@@ -190,6 +191,7 @@ type AsyncDataOptions<DataT> = {
   pick?: string[]
   watch?: MultiWatchSources | false
   getCachedData?: (key: string, nuxtApp: NuxtApp, ctx: AsyncDataRequestContext) => DataT | undefined
+  timeout?: number
 }
 
 type AsyncDataRequestContext = {
@@ -208,6 +210,8 @@ type AsyncData<DataT, ErrorT> = {
 
 interface AsyncDataExecuteOptions {
   dedupe?: 'cancel' | 'defer'
+  timeout?: number
+  signal?: AbortSignal
 }
 
 type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'

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

@@ -145,6 +145,7 @@ type UseFetchOptions<DataT> = {
   getCachedData?: (key: string, nuxtApp: NuxtApp, ctx: AsyncDataRequestContext) => DataT | undefined
   deep?: boolean
   dedupe?: 'cancel' | 'defer'
+  timeout?: number
   default?: () => DataT
   transform?: (input: DataT) => DataT | Promise<DataT>
   pick?: string[]
@@ -169,6 +170,8 @@ type AsyncData<DataT, ErrorT> = {
 
 interface AsyncDataExecuteOptions {
   dedupe?: 'cancel' | 'defer'
+  timeout?: number
+  signal?: AbortSignal
 }
 
 type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'
@@ -195,6 +198,7 @@ type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'
 | `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. |

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

@@ -8,7 +8,7 @@ links:
     size: xs
 ---
 
-Modules are the building blocks of Nuxt. Kit provides a set of utilities to help you create and use modules. You can use these utilities to create your own modules or to reuse existing modules. For example, you can use the `defineNuxtModule` function to define a module and the `installModule` function to install a module programmatically.
+Modules are the building blocks of Nuxt. Kit provides a set of utilities to help you create and use modules. You can use these utilities to create your own modules or to reuse existing modules. For example, you can use the `defineNuxtModule` function to define a module and specify dependencies using the `moduleDependencies` option.
 
 ## `defineNuxtModule`
 
@@ -62,6 +62,7 @@ export function defineNuxtModule<TOptions extends ModuleOptions> (): {
 | `defaults`         | `T \| ((nuxt: Nuxt) => T)`{lang="ts"}                                | `false`  | Default options for the module. If a function is provided, it will be called with the Nuxt instance as the first argument. |
 | `schema`           | `T`                                                                  | `false`  | Schema for the module options. If provided, options will be applied to the schema.                              |
 | `hooks`            | `Partial<NuxtHooks>`{lang="ts"}                                      | `false`  | Hooks to be installed for the module. If provided, the module will install the hooks.                           |
+| `moduleDependencies` | `Record<string, ModuleDependency> \| ((nuxt: Nuxt) => Record<string, ModuleDependency>)`{lang="ts"} | `false`  | Dependencies on other modules with version constraints and configuration. Can be an object or a function that receives the Nuxt instance. See [example](#specifying-module-dependencies). |
 | `onInstall`        | `(nuxt: Nuxt) => Awaitable<void>`{lang="ts"}                        | `false`  | Lifecycle hook called when the module is first installed. Requires `meta.name` and `meta.version` to be defined. |
 | `onUpgrade`        | `(options: T, nuxt: Nuxt, previousVersion: string) => Awaitable<void>`{lang="ts"} | `false`  | Lifecycle hook called when the module is upgraded to a newer version. Requires `meta.name` and `meta.version` to be defined. |
 | `setup`            | `(this: void, resolvedOptions: T, nuxt: Nuxt) => Awaitable<void \| false \| ModuleSetupInstallResult>`{lang="ts"} | `false`  | Setup function for the module. If provided, the module will call the setup function.    |
@@ -239,8 +240,93 @@ export default defineNuxtModule({
 })
 ```
 
+#### Specifying Module Dependencies
+
+You can use the `moduleDependencies` option to declare dependencies on other modules. This provides a robust way to ensure proper setup order, version compatibility, and configuration management.
+
+The `moduleDependencies` option can be either an object or a function that receives the Nuxt instance:
+
+##### Example
+
+```ts
+import { defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  meta: {
+    name: 'my-module',
+  },
+  moduleDependencies: {
+    '@nuxtjs/tailwindcss': {
+      // Specify a version constraint (semver format)
+      version: '>=6.0.0',
+      // Configuration that overrides user settings
+      overrides: {
+        exposeConfig: true,
+      },
+      // Configuration that sets defaults but respects user settings
+      defaults: {
+        config: {
+          darkMode: 'class',
+        },
+      },
+    },
+    '@nuxtjs/fontaine': {
+      // Optional dependencies won't be installed but ensure that options
+      // can be set if they _are_ installed
+      optional: true,
+      defaults: {
+        fonts: [
+          {
+            family: 'Roboto',
+            fallbacks: ['Impact'],
+          },
+        ],
+      },
+    },
+  },
+  setup (options, nuxt) {
+
+  },
+})
+```
+
+You can also use a function to dynamically determine dependencies based on the Nuxt configuration:
+
+```ts
+import { defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  meta: {
+    name: 'my-module',
+  },
+  moduleDependencies (nuxt) {
+    const dependencies: Record<string, any> = {
+      '@nuxtjs/tailwindcss': {
+        version: '>=6.0.0',
+      },
+    }
+
+    // Conditionally add dependencies based on Nuxt config
+    if (nuxt.options.experimental?.someFeature) {
+      dependencies['@nuxtjs/fontaine'] = {
+        optional: true,
+      }
+    }
+
+    return dependencies
+  },
+  setup (options, nuxt) {
+    // Your setup logic runs after all dependencies are initialized
+  },
+})
+```
+
 ## `installModule`
 
+::callout{type="warning"}
+**Deprecated:** Use the [`moduleDependencies`](#specifying-module-dependencies) option in `defineNuxtModule` instead. The `installModule` function will be removed (or may become non-blocking) in a future version.
+::
+
 Install specified Nuxt module programmatically. This is helpful when your module depends on other modules. You can pass the module options as an object to `inlineOptions` and they will be passed to the module's `setup` function.
 
 ### Usage

package/3.api/5.kit/11.nitro.md

@@ -197,6 +197,10 @@ Add plugin to extend Nitro's runtime behavior.
 You can read more about Nitro plugins in the [Nitro documentation](https://nitro.build/guide/plugins).
 ::
 
+::warning
+It is necessary to explicitly import `defineNitroPlugin` from `nitropack/runtime` within your plugin file. The same requirement applies to utilities such as `useRuntimeConfig`.
+::
+
 ### Usage
 
 ```ts twoslash

package/3.api/5.kit/14.builder.md

@@ -14,6 +14,10 @@ Nuxt have builders based on [Vite](https://github.com/nuxt/nuxt/tree/main/packag
 
 Extends the Vite configuration. Callback function can be called multiple times, when applying to both client and server builds.
 
+::warning
+This hook is now deprecated, and we recommend using a Vite plugin instead with a `config` hook, or — for environment-specific configuration — the `applyToEnvironment` hook.
+::
+
 ### Usage
 
 ```ts twoslash
@@ -30,6 +34,45 @@ export default defineNuxtModule({
 })
 ```
 
+For environment-specific configuration in Nuxt 5+, use `addVitePlugin()` instead:
+
+```ts twoslash
+import { addVitePlugin, defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup () {
+    // For global configuration (affects all environments)
+    addVitePlugin(() => ({
+      name: 'my-global-plugin',
+      config (config) {
+        // This runs before environment setup
+        config.optimizeDeps ||= {}
+        config.optimizeDeps.include ||= []
+        config.optimizeDeps.include.push('cross-fetch')
+      },
+    }))
+
+    // For environment-specific configuration
+    addVitePlugin(() => ({
+      name: 'my-client-plugin',
+      applyToEnvironment (environment) {
+        return environment.name === 'client'
+      },
+      configEnvironment (name, config) {
+        // This only affects the client environment
+        config.optimizeDeps ||= {}
+        config.optimizeDeps.include ||= []
+        config.optimizeDeps.include.push('client-only-package')
+      },
+    }))
+  },
+})
+```
+
+::warning
+**Important:** The `config` hook runs before `applyToEnvironment` and modifies the global configuration. Use `configEnvironment` for environment-specific configuration changes.
+::
+
 ### Type
 
 ```ts twoslash
@@ -54,8 +97,8 @@ Checkout Vite website for more information about its configuration.
 | --------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------ |
 | `dev`     | `boolean` | `false`  | If set to `true`, the callback function will be called when building in development mode.                    |
 | `build`   | `boolean` | `false`  | If set to `true`, the callback function will be called when building in production mode.                     |
-| `server`  | `boolean` | `false`  | If set to `true`, the callback function will be called when building the server bundle.                      |
-| `client`  | `boolean` | `false`  | If set to `true`, the callback function will be called when building the client bundle.                      |
+| `server`  | `boolean` | `false`  | If set to `true`, the callback function will be called when building the server bundle. **Deprecated in Nuxt 5+.** Use `addVitePlugin()` with `applyToEnvironment()` instead. |
+| `client`  | `boolean` | `false`  | If set to `true`, the callback function will be called when building the client bundle. **Deprecated in Nuxt 5+.** Use `addVitePlugin()` with `applyToEnvironment()` instead. |
 | `prepend` | `boolean` | `false`  | If set to `true`, the callback function will be prepended to the array with `unshift()` instead of `push()`. |
 
 ## `extendWebpackConfig`
@@ -111,6 +154,10 @@ Checkout webpack website for more information about its configuration.
 
 Append Vite plugin to the config.
 
+::warning
+In Nuxt 5+, plugins registered with `server: false` or `client: false` options will not have their `config` or `configResolved` hooks called. Instead, use the `applyToEnvironment()` method instead for environment-specific plugins.
+::
+
 ### Usage
 
 ```ts twoslash
@@ -131,6 +178,15 @@ export default defineNuxtModule({
   },
   setup (options) {
     addVitePlugin(svg4VuePlugin(options.svg4vue))
+
+    // or, to add a vite plugin to only one environment
+    addVitePlugin(() => ({
+      name: 'my-client-plugin',
+      applyToEnvironment (environment) {
+        return environment.name === 'client'
+      },
+      // ... rest of your client-only plugin
+    }))
   },
 })
 ```
@@ -159,8 +215,8 @@ See [Vite website](https://vite.dev/guide/api-plugin.html) for more information
 | --------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------ |
 | `dev`     | `boolean` | `false`  | If set to `true`, the callback function will be called when building in development mode.                    |
 | `build`   | `boolean` | `false`  | If set to `true`, the callback function will be called when building in production mode.                     |
-| `server`  | `boolean` | `false`  | If set to `true`, the callback function will be called when building the server bundle.                      |
-| `client`  | `boolean` | `false`  | If set to `true`, the callback function will be called when building the client bundle.                      |
+| `server`  | `boolean` | `false`  | If set to `true`, the callback function will be called when building the server bundle. **Deprecated in Nuxt 5+.** Use `applyToEnvironment()` instead. |
+| `client`  | `boolean` | `false`  | If set to `true`, the callback function will be called when building the client bundle. **Deprecated in Nuxt 5+.** Use `applyToEnvironment()` instead. |
 | `prepend` | `boolean` | `false`  | If set to `true`, the callback function will be prepended to the array with `unshift()` instead of `push()`. |
 
 ## `addWebpackPlugin`

package/3.api/5.kit/15.examples.md

@@ -22,11 +22,9 @@ import { buildNuxt, loadNuxt } from '@nuxt/kit'
 async function getViteConfig () {
   const nuxt = await loadNuxt({ cwd: process.cwd(), dev: false, overrides: { ssr: false } })
   return new Promise((resolve, reject) => {
-    nuxt.hook('vite:extendConfig', (config, { isClient }) => {
-      if (isClient) {
-        resolve(config)
-        throw new Error('_stop_')
-      }
+    nuxt.hook('vite:extend', (config) => {
+      resolve(config)
+      throw new Error('_stop_')
     })
     buildNuxt(nuxt).catch((err) => {
       if (!err.toString().includes('_stop_')) {

package/3.api/5.kit/5.components.md

@@ -113,6 +113,7 @@ function addComponent (options: AddComponentOptions): void
 | ------------------ | ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |  
 | `name`             | `string`                     | `true`   | Component name.                                                                                                 |
 | `filePath`         | `string`                     | `true`   | Path to the component.                                                                                          |
+| `declarationPath`  | `string`                     | `false`  | Path to component's declaration file. It is used to generate components' [type templates](/docs/4.x/api/kit/templates#addtypetemplate); if not provided, `filePath` is used instead. |
 | `pascalName`       | `string`                     | `false`  | Pascal case component name. If not provided, it will be generated from the component name.                      |
 | `kebabName`        | `string`                     | `false`  | Kebab case component name. If not provided, it will be generated from the component name.                       |
 | `export`           | `string`                     | `false`  | Specify named or default export. If not provided, it will be set to `'default'`.                                 |

package/3.api/5.kit/9.head.md

@@ -0,0 +1,132 @@
+---
+title: Head
+description: Nuxt Kit provides utilities to help you manage head configuration in modules.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/kit/src/head.ts
+    size: xs
+---
+
+## `setGlobalHead`
+
+Sets global head configuration for your Nuxt application. This utility allows modules to programmatically configure meta tags, links, scripts, and other head elements that will be applied across all pages.
+
+The provided head configuration will be merged with any existing head configuration using deep merging, with your provided values taking precedence.
+
+::tip
+This is particularly useful for modules that need to inject global meta tags, stylesheets, or scripts into the application head.
+::
+
+### Type
+
+```ts twoslash
+// @errors: 2391
+// ---cut---
+import type { SerializableHead } from '@unhead/vue/types'
+
+interface AppHeadMetaObject extends SerializableHead {
+  charset?: string
+  viewport?: string
+}
+
+function setGlobalHead (head: AppHeadMetaObject): void
+```
+
+### Parameters
+
+#### `head`
+
+**Type**: `AppHeadMetaObject`
+
+An object containing head configuration. All properties are optional and will be merged with existing configuration:
+
+- `charset`: Character encoding for the document
+- `viewport`: Viewport meta tag configuration
+- `meta`: Array of meta tag objects
+- `link`: Array of link tag objects (stylesheets, icons, etc.)
+- `style`: Array of inline style tag objects
+- `script`: Array of script tag objects
+- `noscript`: Array of noscript tag objects
+- `title`: Default page title
+- `titleTemplate`: Template for formatting page titles
+- `bodyAttrs`: Attributes to add to the `<body>` tag
+- `htmlAttrs`: Attributes to add to the `<html>` tag
+
+### Examples
+
+#### Adding Global Meta Tags
+
+```ts
+import { defineNuxtModule, setGlobalHead } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup () {
+    setGlobalHead({
+      meta: [
+        { name: 'theme-color', content: '#ffffff' },
+        { name: 'author', content: 'Your Name' },
+      ],
+    })
+  },
+})
+```
+
+#### Injecting Global Stylesheets
+
+```ts
+import { defineNuxtModule, setGlobalHead } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup () {
+    setGlobalHead({
+      link: [
+        {
+          rel: 'stylesheet',
+          href: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap',
+        },
+      ],
+    })
+  },
+})
+```
+
+#### Adding Global Scripts
+
+```ts
+import { defineNuxtModule, setGlobalHead } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup () {
+    setGlobalHead({
+      script: [
+        {
+          src: 'https://cdn.example.com/analytics.js',
+          async: true,
+          defer: true,
+        },
+      ],
+    })
+  },
+})
+```
+
+#### Setting HTML Attributes
+
+```ts
+import { defineNuxtModule, setGlobalHead } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup () {
+    setGlobalHead({
+      htmlAttrs: {
+        lang: 'en',
+        dir: 'ltr',
+      },
+      bodyAttrs: {
+        class: 'custom-body-class',
+      },
+    })
+  },
+})
+```

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

@@ -75,8 +75,8 @@ Hook                     | Arguments                  | Description
 `schema:beforeWrite`     | `schema`                   | Called before writing the given schema.
 `schema:written`         | -                          | Called after the schema is written.
 `vite:extend`            | `viteBuildContext`         | Allows extending Vite default context.
-`vite:extendConfig`      | `viteInlineConfig, env`    | Allows extending Vite default config.
-`vite:configResolved`    | `viteInlineConfig, env`    | Allows reading the resolved Vite config.
+`vite:extendConfig`      | `viteInlineConfig, env`    | Allows extending Vite default config. **Deprecated in Nuxt 5+.** In Nuxt 5, this operates on a shared configuration rather than separate client/server configs.
+`vite:configResolved`    | `viteInlineConfig, env`    | Allows reading the resolved Vite config. **Deprecated in Nuxt 5+.** In Nuxt 5, this operates on a shared configuration rather than separate client/server configs.
 `vite:serverCreated`     | `viteServer, env`          | Called when the Vite server is created.
 `vite:compiled`          | -                          | Called after Vite server is compiled.
 `webpack:config`         | `webpackConfigs`           | Called before configuring the webpack compiler.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs",
-  "version": "3.19.3",
+  "version": "3.20.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",