@nuxt/docs 4.1.3 → 4.2.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

@@ -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.
@@ -81,19 +221,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
 ```
 
 ::
@@ -110,11 +254,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 +423,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 +538,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 +548,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 +561,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 +1059,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 +1144,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.
 
@@ -1033,8 +1177,13 @@ However, to take advantage of improved type checking, you can opt in to the new
 
 1. **Update your root `tsconfig.json`** to use project references:
 
+   ::note
+   If your `tsconfig.json` currently has an `"extends": "./.nuxt/tsconfig.json"` line, **remove it** before adding the references. Project references and extends are mutually exclusive.
+   ::
+
    ```json
    {
+     // Remove "extends": "./.nuxt/tsconfig.json" if present
      "files": [],
      "references": [
        { "path": "./.nuxt/tsconfig.app.json" },
@@ -1055,9 +1204,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 +1246,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 +1258,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 +1270,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/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

@@ -87,6 +87,44 @@ export default defineNuxtConfig({
 This feature will likely be removed in a near future.
 ::
 
+## 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.
@@ -831,3 +869,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/1.features.md

@@ -61,9 +61,21 @@ There is also a `future` namespace for early opting-in to new features that will
 
 ### compatibilityVersion
 
-This is used for enabling early access to Nuxt features or flags.
+This enables early access to Nuxt features or flags.
 
-It is not configurable yet in Nuxt 4, but once we begin merging breaking changes for v5, it will be possible to enable it.
+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({
+  future: {
+    compatibilityVersion: 5,
+  },
+})
+```
+
+::read-more{to="/docs/4.x/getting-started/upgrade#testing-nuxt-5"}
+Learn more about testing Nuxt 5.
+::
 
 ### multiApp
 

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,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/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'
+
 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/3.api/6.nuxt-config.md

@@ -424,9 +424,60 @@ A unique identifier matching the build. This may contain the hash of the current
 
 The builder to use for bundling the Vue part of your application.
 
-- **Type**: `string`
+Nuxt supports multiple builders for the client-side application. By default, Vite is used, but you can switch to webpack, Rspack, or even provide a custom builder implementation.
+
+- **Type**: `'vite' | 'webpack' | 'rspack' | string | { bundle: (nuxt: Nuxt) => Promise<void> }`
 - **Default:** `"@nuxt/vite-builder"`
 
+**Using supported builders:**
+
+```ts
+export default defineNuxtConfig({
+  // default - uses @nuxt/vite-builder
+  // builder: 'vite',
+
+  // uses @nuxt/webpack-builder
+  // builder: 'webpack',
+
+  // uses @nuxt/rspack-builder
+  builder: 'rspack',
+})
+```
+
+If you are using `webpack` or `rspack` you will need to make sure `@nuxt/webpack-builder` or `@nuxt/rspack-builder` is explicitly installed in your project.
+
+**Using a custom builder object:**
+
+You can provide a custom builder by passing an object with a `bundle` function:
+
+```ts
+export default defineNuxtConfig({
+  builder: {
+    async bundle (nuxt) {
+      const entry = await resolvePath(resolve(nuxt.options.appDir, 'entry'))
+
+      // Build client and server bundles
+      await buildClient(nuxt, entry)
+      if (nuxt.options.ssr) {
+        await buildServer(nuxt, entry)
+      }
+
+      // ... it's a bit more complicated than that, of course!
+    },
+  },
+})
+```
+
+**Creating a custom builder package:**
+
+To create a custom builder as a separate package, it should export a `bundle` function. You can then specify the package name in your `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  builder: 'my-custom-builder',
+})
+```
+
 ## compatibilityDate
 
 Specify a compatibility date for your app.
@@ -668,7 +719,8 @@ Configure shared esbuild options used within Nuxt and passed to other builders,
 
 ## experimental
 
-::read-more{to="/docs/4.x/guide/going-further/experimental-features"} Learn more about Nuxt's experimental features.
+::read-more{to="/docs/4.x/guide/going-further/experimental-features"}
+Learn more about Nuxt's experimental features.
 ::
 
 ## extends
@@ -701,12 +753,14 @@ The extensions that should be resolved by the Nuxt resolver.
 
 ## features
 
-::read-more{to="/docs/4.x/guide/going-further/features#features"} Learn more about Nuxt's opt-in features.
+::read-more{to="/docs/4.x/guide/going-further/features#features"}
+Learn more about Nuxt's opt-in features.
 ::
 
 ## future
 
-::read-more{to="/docs/4.x/guide/going-further/features#features"} Learn more about opting-in to new features that will become default in a future (possibly major) version of the framework,
+::read-more{to="/docs/4.x/guide/going-further/features#features"}
+Learn more about opting-in to new features that will become default in a future (possibly major) version of the framework.
 ::
 
 ## hooks
@@ -1218,6 +1272,23 @@ export default defineNuxtConfig({
 })
 ```
 
+## server
+
+Configuration for Nuxt's server builder.
+
+### `builder`
+
+Specify the server builder to use for bundling the server part of your application.
+
+By default, Nuxt uses `@nuxt/nitro-server`, which provides standalone Nitro integration. This architecture allows for different Nitro integration patterns, such as using Nitro as a Vite plugin (with the Vite Environment API).
+
+- **Type**: `string | { bundle: (nuxt: Nuxt) => Promise<void> }`
+- **Default:** `"@nuxt/nitro-server"`
+
+::callout{type="warning"}
+This option is intended for internal use and the API is not finalized. Please open an issue before relying on the current implementation.
+::
+
 ## serverDir
 
 Define the server directory of your Nuxt application, where Nitro routes, middleware and plugins are kept.

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

@@ -31,8 +31,8 @@ If your issue concerns Vue or Vite, please try to reproduce it first with the Vu
 **Nuxt**:
 
 ::card-group
-  :card{title="Nuxt on StackBlitz" icon="i-simple-icons-stackblitz" to="https://nuxt.new/s/v3" target="_blank"}
-  :card{title="Nuxt on CodeSandbox" icon="i-simple-icons-codesandbox" to="https://nuxt.new/c/v3" target="_blank"}
+  :card{title="Nuxt on StackBlitz" icon="i-simple-icons-stackblitz" to="https://nuxt.new/s/v4" target="_blank"}
+  :card{title="Nuxt on CodeSandbox" icon="i-simple-icons-codesandbox" to="https://nuxt.new/c/v4" target="_blank"}
 ::
 
 **Vue**:

package/5.community/6.roadmap.md

@@ -32,7 +32,7 @@ Milestone    | Expected date | Notes
 -------------|---------------|------------------------------------------------------------------------|-----------------------
 SEO & PWA    | 2025          | [nuxt/nuxt#18395](https://github.com/nuxt/nuxt/discussions/18395)      | Migrating from [nuxt-community/pwa-module](https://github.com/nuxt-community/pwa-module) for built-in SEO utils and service worker support
 Assets       | 2025          | [nuxt/nuxt#22012](https://github.com/nuxt/nuxt/discussions/22012)      | Allow developers and modules to handle loading third-party assets.
-Translations | -             | [nuxt/translations#4](https://github.com/nuxt/translations/discussions/4) ([request access](https://github.com/nuxt/nuxt/discussions/16054)) | A collaborative project for a stable translation process for Nuxt docs. Currently pending for ideas and documentation tooling support (content v2 with remote sources).
+Translations | -             | [nuxt/nuxt.com#1711](https://github.com/nuxt/nuxt.com/issues/1711)     | A collaborative project for a stable translation process for Nuxt docs. Currently pending for ideas and documentation tooling support.
 
 ## Core Modules Roadmap
 

package/package.json

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