@nuxt/docs-nightly 4.2.0-29344722.285eac31 → 4.2.0-29345484.1f69d1e1

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

@@ -34,6 +34,146 @@ bun x nuxt upgrade
 
 To use the latest Nuxt build and test features before their release, read about the [nightly release channel](/docs/4.x/guide/going-further/nightly-release-channel) guide.
 
+## Testing Nuxt 5
+
+Nuxt 5 is **currently in development**. Until the release, it is possible to test many of Nuxt 5's breaking changes from Nuxt version 4.2+.
+
+### Opting in to Nuxt 5
+
+First, upgrade Nuxt to the [latest release](https://github.com/nuxt/nuxt/releases).
+
+Then you can set your `future.compatibilityVersion` to match Nuxt 5 behavior:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  future: {
+    compatibilityVersion: 5,
+  },
+})
+```
+
+When you set your `future.compatibilityVersion` to `5`, defaults throughout your Nuxt configuration will change to opt in to Nuxt v5 behavior, including:
+
+- **Vite Environment API**: Automatically enables the new [Vite Environment API](#migration-to-vite-environment-api) for improved build configuration
+- Other Nuxt 5 improvements and changes as they become available
+
+::note
+This section is subject to change until the final release, so please check back here regularly if you are testing Nuxt 5 using `future.compatibilityVersion: 5`.
+::
+
+Breaking or significant changes will be noted below along with migration steps for backward/forward compatibility.
+
+### Migration to Vite Environment API
+
+🚦 **Impact Level**: Medium
+
+#### What Changed
+
+Nuxt 5 migrates to Vite 6's new [Environment API](https://vite.dev/guide/api-environment), which formalizes the concept of environments and provides better control over configuration per environment.
+
+Previously, Nuxt used separate client and server Vite configurations. Now, Nuxt uses a shared Vite configuration with environment-specific plugins that use the `applyToEnvironment()` method to target specific environments.
+
+::tip
+You can test this feature early by setting `future.compatibilityVersion: 5` (see [Testing Nuxt 5](#testing-nuxt-5)) or by enabling it explicitly with `experimental.viteEnvironmentApi: true`.
+::
+
+**Key changes:**
+
+1. **Deprecated environment-specific `extendViteConfig()`**: The `server` and `client` options in `extendViteConfig()` are deprecated and will show warnings when used.
+
+2. **Changed plugin registration**: Vite plugins registered with `addVitePlugin()` and only targeting one environment (by passing `server: false` or `client: false`) will not have their `config` or `configResolved` hooks called.
+
+3. **Shared configuration**: The `vite:extendConfig` and `vite:configResolved` hooks now work with a shared configuration rather than separate client/server configs.
+
+#### Reasons for Change
+
+The Vite Environment API provides:
+- Better consistency between development and production builds
+- More granular control over environment-specific configuration
+- Improved performance and plugin architecture
+- Support for custom environments beyond just client and server
+
+#### Migration Steps
+
+##### 1. Migrate to use Vite plugins
+
+We would recommend you use a Vite plugin instead of `extendViteConfig`, `vite:configResolved` and `vite:extendConfig`.
+
+```ts
+// Before
+extendViteConfig((config) => {
+  config.optimizeDeps.include.push('my-package')
+}, { server: false })
+
+nuxt.hook('vite:extendConfig' /* or vite:configResolved */, (config, { isClient }) => {
+  if (isClient) {
+    config.optimizeDeps.include.push('my-package')
+  }
+})
+
+// After
+addVitePlugin(() => ({
+  name: 'my-plugin',
+  config (config) {
+    // you can set global vite configuration here
+  },
+  configResolved (config) {
+    // you can access the fully resolved vite configuration here
+  },
+  configEnvironment (name, config) {
+    // you can set environment-specific vite configuration here
+    if (name === 'client') {
+      config.optimizeDeps ||= {}
+      config.optimizeDeps.include ||= []
+      config.optimizeDeps.include.push('my-package')
+    }
+  },
+  applyToEnvironment (environment) {
+    return environment.name === 'client'
+  },
+}))
+```
+
+##### 2. Migrate Vite plugins to use environments
+
+Instead of using `addVitePlugin` with `server: false` or `client: false`, you can instead use the new `applyToEnvironment` hook within your plugin.
+
+```ts
+// Before
+addVitePlugin(() => ({
+  name: 'my-plugin',
+  config (config) {
+    config.optimizeDeps.include.push('my-package')
+  },
+}), { client: false })
+
+// After
+addVitePlugin(() => ({
+  name: 'my-plugin',
+  config (config) {
+    // you can set global vite configuration here
+  },
+  configResolved (config) {
+    // you can access the fully resolved vite configuration here
+  },
+  configEnvironment (name, config) {
+    // you can set environment-specific vite configuration here
+    if (name === 'client') {
+      config.optimizeDeps ||= {}
+      config.optimizeDeps.include ||= []
+      config.optimizeDeps.include.push('my-package')
+    }
+  },
+  applyToEnvironment (environment) {
+    return environment.name === 'client'
+  },
+}))
+```
+
+::read-more{to="https://vite.dev/guide/api-environment" target="_blank"}
+Learn more about Vite's Environment API
+::
+
 ## Migrating to Nuxt 4
 
 Nuxt 4 includes significant improvements and changes. This guide will help you migrate your existing Nuxt 3 application to Nuxt 4.
@@ -110,11 +250,11 @@ Nuxt now defaults to a new directory structure, with backwards compatibility (so
 
 #### What Changed
 
-* the new Nuxt default `srcDir` is `app/` by default, and most things are resolved from there.
-* `serverDir` now defaults to `<rootDir>/server` rather than `<srcDir>/server`
-* `layers/`, `modules/` and `public/` are resolved relative to `<rootDir>` by default
-* if using [Nuxt Content v2.13+](https://github.com/nuxt/content/pull/2649), `content/` is resolved relative to `<rootDir>`
-* a new `dir.app` is added, which is the directory we look for `router.options.ts` and `spa-loading-template.html` - this defaults to `<srcDir>/`
+- the new Nuxt default `srcDir` is `app/` by default, and most things are resolved from there.
+- `serverDir` now defaults to `<rootDir>/server` rather than `<srcDir>/server`
+- `layers/`, `modules/` and `public/` are resolved relative to `<rootDir>` by default
+- if using [Nuxt Content v2.13+](https://github.com/nuxt/content/pull/2649), `content/` is resolved relative to `<rootDir>`
+- a new `dir.app` is added, which is the directory we look for `router.options.ts` and `spa-loading-template.html` - this defaults to `<srcDir>/`
 
 <details>
 
@@ -279,15 +419,15 @@ Now modules are loaded in the correct order:
 2. **Project modules last** (highest priority)
 
 This affects both:
-* Modules defined in the `modules` array in `nuxt.config.ts`
-* Auto-discovered modules from the `modules/` directory
+- Modules defined in the `modules` array in `nuxt.config.ts`
+- Auto-discovered modules from the `modules/` directory
 
 #### Reasons for Change
 
 This change ensures that:
-* Extended layers have lower priority than the consuming project
-* Module execution order matches the intuitive layer inheritance pattern
-* Module configuration and hooks work as expected in multi-layer setups
+- Extended layers have lower priority than the consuming project
+- Module execution order matches the intuitive layer inheritance pattern
+- Module configuration and hooks work as expected in multi-layer setups
 
 #### Migration Steps
 
@@ -394,9 +534,9 @@ export default defineNuxtConfig({
 [Unhead](https://unhead.unjs.io/), used to generate `<head>` tags, has been updated to version 2. While mostly compatible it includes several breaking changes
 for lower-level APIs.
 
-* Removed props: `vmid`, `hid`, `children`, `body`.
-* Promise input no longer supported.
-* Tags are now sorted using Capo.js by default.
+- Removed props: `vmid`, `hid`, `children`, `body`.
+- Promise input no longer supported.
+- Tags are now sorted using Capo.js by default.
 
 #### Migration Steps
 
@@ -404,7 +544,7 @@ The above changes should have minimal impact on your app.
 
 If you have issues you should verify:
 
-* You're not using any of the removed props.
+- You're not using any of the removed props.
 
 ```diff
 useHead({
@@ -417,7 +557,7 @@ useHead({
 })
 ```
 
-* If you're using [Template Params](https://unhead.unjs.io/docs/head/guides/plugins/template-params) or [Alias Tag Sorting](https://unhead.unjs.io/docs/head/guides/plugins/alias-sorting), you will need to explicitly opt in to these features now.
+- If you're using [Template Params](https://unhead.unjs.io/docs/head/guides/plugins/template-params) or [Alias Tag Sorting](https://unhead.unjs.io/docs/head/guides/plugins/alias-sorting), you will need to explicitly opt in to these features now.
 
 ```ts
 import { AliasSortingPlugin, TemplateParamsPlugin } from '@unhead/vue/plugins'
@@ -915,9 +1055,9 @@ Finally, providing code serialization functions directly within Nuxt is not idea
 
 We have raised PRs to update modules using EJS syntax, but if you need to do this yourself, you have three backwards/forwards-compatible alternatives:
 
-* Moving your string interpolation logic directly into `getContents()`.
-* Using a custom function to handle the replacement, such as in https://github.com/nuxt-modules/color-mode/pull/240.
-* Use `es-toolkit/compat` (a drop-in replacement for lodash template), as a dependency of _your_ project rather than Nuxt:
+- Moving your string interpolation logic directly into `getContents()`.
+- Using a custom function to handle the replacement, such as in https://github.com/nuxt-modules/color-mode/pull/240.
+- Use `es-toolkit/compat` (a drop-in replacement for lodash template), as a dependency of _your_ project rather than Nuxt:
 
 ```diff
 + import { readFileSync } from 'node:fs'
@@ -1000,11 +1140,11 @@ There are two approaches:
 Nuxt now generates separate TypeScript configurations for different contexts to provide better type-checking experiences:
 
 1. **New TypeScript configuration files**: Nuxt now generates additional TypeScript configurations:
-   * `.nuxt/tsconfig.app.json` - For your app code (Vue components, composables, etc.)
-   * `.nuxt/tsconfig.server.json` - For your server-side code (Nitro/server directory)  
-   * `.nuxt/tsconfig.node.json` - For your build-time code (modules, `nuxt.config.ts`, etc.)
-   * `.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
+   - `.nuxt/tsconfig.app.json` - For your app code (Vue components, composables, etc.)
+   - `.nuxt/tsconfig.server.json` - For your server-side code (Nitro/server directory)  
+   - `.nuxt/tsconfig.node.json` - For your build-time code (modules, `nuxt.config.ts`, etc.)
+   - `.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
 
 2. **Backward compatibility**: Existing projects that extend `.nuxt/tsconfig.json` will continue to work as before.
 
@@ -1055,9 +1195,9 @@ However, to take advantage of improved type checking, you can opt in to the new
    ```
 
 4. **Move all type augmentations into their appropriate context**:
-   * If you are augmenting types for the app context, move the files to the `app/` directory.
-   * If you are augmenting types for the server context, move the files to the `server/` directory.
-   * If you are augmenting types that are **shared between the app and server**, move the files to the `shared/` directory.
+   - If you are augmenting types for the app context, move the files to the `app/` directory.
+   - If you are augmenting types for the server context, move the files to the `server/` directory.
+   - If you are augmenting types that are **shared between the app and server**, move the files to the `shared/` directory.
 
     ::warning
     Augmenting types from outside the `app/`, `server/`, or `shared/` directories will not work with the new project references setup.
@@ -1097,11 +1237,11 @@ The new configuration provides better type safety and IntelliSense for projects
 
 Four experimental features are no longer configurable in Nuxt 4:
 
-* `experimental.treeshakeClientOnly` will be `true` (default since v3.0)
-* `experimental.configSchema` will be `true` (default since v3.3)
-* `experimental.polyfillVueUseHead` will be `false` (default since v3.4)
-* `experimental.respectNoSSRHeader` will be `false` (default since v3.4)
-* `vite.devBundler` is no longer configurable - it will use `vite-node` by default
+- `experimental.treeshakeClientOnly` will be `true` (default since v3.0)
+- `experimental.configSchema` will be `true` (default since v3.3)
+- `experimental.polyfillVueUseHead` will be `false` (default since v3.4)
+- `experimental.respectNoSSRHeader` will be `false` (default since v3.4)
+- `vite.devBundler` is no longer configurable - it will use `vite-node` by default
 
 #### Reasons for Change
 
@@ -1109,9 +1249,9 @@ These options have been set to their current values for some time and we do not
 
 #### Migration Steps
 
-* `polyfillVueUseHead` is implementable in user-land with [this plugin](https://github.com/nuxt/nuxt/blob/f209158352b09d1986aa320e29ff36353b91c358/packages/nuxt/src/head/runtime/plugins/vueuse-head-polyfill.ts#L10-L11)
+- `polyfillVueUseHead` is implementable in user-land with [this plugin](https://github.com/nuxt/nuxt/blob/f209158352b09d1986aa320e29ff36353b91c358/packages/nuxt/src/head/runtime/plugins/vueuse-head-polyfill.ts#L10-L11)
 
-* `respectNoSSRHeader`is implementable in user-land with [server middleware](https://github.com/nuxt/nuxt/blob/c660b39447f0d5b8790c0826092638d321cd6821/packages/nuxt/src/core/runtime/nitro/no-ssr.ts#L8-L9)
+- `respectNoSSRHeader`is implementable in user-land with [server middleware](https://github.com/nuxt/nuxt/blob/c660b39447f0d5b8790c0826092638d321cd6821/packages/nuxt/src/core/runtime/nitro/no-ssr.ts#L8-L9)
 
 ### Removal of Top-Level `generate` Configuration
 
@@ -1121,8 +1261,8 @@ These options have been set to their current values for some time and we do not
 
 The top-level `generate` configuration option is no longer available in Nuxt 4. This includes all of its properties:
 
-* `generate.exclude` - for excluding routes from prerendering
-* `generate.routes` - for specifying routes to prerender
+- `generate.exclude` - for excluding routes from prerendering
+- `generate.routes` - for specifying routes to prerender
 
 #### Reasons for Change
 

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

@@ -895,3 +895,27 @@ To use this feature, you need to:
 ::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/1.features.md

@@ -63,7 +63,7 @@ There is also a `future` namespace for early opting-in to new features that will
 
 This enables early access to Nuxt features or flags.
 
-Setting `compatibilityVersion` to `5` changes defaults throughout your Nuxt configuration to opt-in to Nuxt v5 behaviour.
+Setting `compatibilityVersion` to `5` changes defaults throughout your Nuxt configuration to opt in to Nuxt v5 behaviour, including enabling the [Vite Environment API](/docs/4.x/guide/going-further/experimental-features#viteenvironmentapi).
 
 ```ts
 export default defineNuxtConfig({
@@ -73,6 +73,10 @@ export default defineNuxtConfig({
 })
 ```
 
+::read-more{to="/docs/4.x/getting-started/upgrade#testing-nuxt-5"}
+Learn more about testing Nuxt 5.
+::
+
 ### multiApp
 
 This enables early access to the experimental multi-app support. You can follow the [tracker issue #21635](https://github.com/nuxt/nuxt/issues/21635) to see the progress of multi-app support in Nuxt.

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/4.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,7 +234,7 @@ export default defineNuxtConfig({
 
 ## Multi-Layer Support for Nuxt Modules
 
-You can use the [`getLayerDirectories`](/docs/api/kit/layers#getlayerdirectories) utility from Nuxt Kit to support custom multi-layer handling for your 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.
 
 ```ts [modules/my-module.ts]
 import { defineNuxtModule, getLayerDirectories } from 'nuxt/kit'

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

@@ -79,6 +79,24 @@ export default defineNuxtModule({
 })
 ```
 
+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`.
 ::

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/14.builder.md

@@ -15,7 +15,7 @@ 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.
+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
@@ -34,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
@@ -58,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`
@@ -115,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
@@ -135,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
+    }))
   },
 })
 ```
@@ -163,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/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. **Deprecated.** We recommend adding a Vite plugin with a `config` hook.
-`vite:configResolved`    | `viteInlineConfig, env`    | Allows reading the resolved Vite config. **Deprecated.** We recommend adding a Vite plugin with a `configResolved` hook.
+`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-nightly",
-  "version": "4.2.0-29344722.285eac31",
+  "version": "4.2.0-29345484.1f69d1e1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",