@nuxt/docs 4.1.2 → 4.2.0

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

@@ -5,12 +5,42 @@ description: "Enable Nuxt experimental features to unlock new possibilities."
 
 Nuxt includes experimental features that you can enable in your configuration file.
 
-Internally, Nuxt uses `@nuxt/schema` to define these experimental features. You can refer to the [API documentation](/docs/api/configuration/nuxt-config#experimental) or the [source code](https://github.com/nuxt/nuxt/blob/main/packages/schema/src/config/experimental.ts) for more information.
+Internally, Nuxt uses `@nuxt/schema` to define these experimental features. You can refer to the [API documentation](/docs/4.x/api/configuration/nuxt-config#experimental) or the [source code](https://github.com/nuxt/nuxt/blob/main/packages/schema/src/config/experimental.ts) for more information.
 
 ::note
 Note that these features are experimental and could be removed or modified in the future.
 ::
 
+## alwaysRunFetchOnKeyChange
+
+Whether to run `useFetch` when the key changes, even if it is set to `immediate: false` and it has not been triggered yet.
+
+`useFetch` and `useAsyncData` will always run when the key changes if `immediate: true` or if it has been already triggered.
+
+This flag is disabled by default, but you can enable this feature:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    alwaysRunFetchOnKeyChange: true,
+  },
+})
+```
+
+## appManifest
+
+Use app manifests to respect route rules on client-side.
+
+This flag is enabled by default, but you can disable this feature:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    appManifest: false,
+  },
+})
+```
+
 ## asyncContext
 
 Enable native async context to be accessible for nested composables in Nuxt and in Nitro. This opens the possibility to use composables inside async composables and reduce the chance to get the `Nuxt instance is unavailable` error.
@@ -18,8 +48,8 @@ Enable native async context to be accessible for nested composables in Nuxt and
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    asyncContext: true
-  }
+    asyncContext: true,
+  },
 })
 ```
 
@@ -34,8 +64,8 @@ Enables generation of an async entry point for the Vue bundle, aiding module fed
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    asyncEntry: true
-  }
+    asyncEntry: true,
+  },
 })
 ```
 
@@ -43,13 +73,13 @@ export default defineNuxtConfig({
 
 Externalizes `vue`, `@vue/*` and `vue-router` when building.
 
-*Enabled by default.*
+This flag is enabled by default, but you can disable this feature:
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    externalVue: true
-  }
+    externalVue: false,
+  },
 })
 ```
 
@@ -57,72 +87,126 @@ 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.
 
-If you set this to `'automatic-immediate'` Nuxt will reload the current route immediately, instead of waiting for a navigation. This is useful for chunk errors that are not triggered by navigation, e.g., when your Nuxt app fails to load a [lazy component](/docs/guide/directory-structure/app/components#dynamic-imports). A potential downside of this behavior is undesired reloads, e.g., when your app does not need the chunk that caused the error.
+By default, Nuxt will also perform a reload of the new route when a chunk fails to load when navigating to a new route (`automatic`).
+
+Setting `automatic-immediate` will lead Nuxt to perform a reload of the current route right when a chunk fails to load (instead of waiting for navigation). This is useful for chunk errors that are not triggered by navigation, e.g., when your Nuxt app fails to load a [lazy component](/docs/4.x/guide/directory-structure/app/components#dynamic-imports). A potential downside of this behavior is undesired reloads, e.g., when your app does not need the chunk that caused the error.
 
 You can disable automatic handling by setting this to `false`, or handle chunk errors manually by setting it to `manual`.
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    emitRouteChunkError: 'automatic' // or 'automatic-immediate', 'manual' or false
-  }
+    emitRouteChunkError: 'automatic', // or 'automatic-immediate', 'manual' or false
+  },
+})
+```
+
+## enforceModuleCompatibility
+
+Whether Nuxt should throw an error (and fail to load) if a Nuxt module is incompatible.
+
+This feature is disabled by default.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    enforceModuleCompatibility: true,
+  },
 })
 ```
 
 ## restoreState
 
-Allows Nuxt app state to be restored from `sessionStorage` when reloading the page after a chunk error or manual [`reloadNuxtApp()`](/docs/api/utils/reload-nuxt-app) call.
+Allows Nuxt app state to be restored from `sessionStorage` when reloading the page after a chunk error or manual [`reloadNuxtApp()`](/docs/4.x/api/utils/reload-nuxt-app) call.
 
 To avoid hydration errors, it will be applied only after the Vue app has been mounted, meaning there may be a flicker on initial load.
 
 ::important
 Consider carefully before enabling this as it can cause unexpected behavior,
-and consider providing explicit keys to [`useState`](/docs/api/composables/use-state) as auto-generated keys may not match across builds.
+and consider providing explicit keys to [`useState`](/docs/4.x/api/composables/use-state) as auto-generated keys may not match across builds.
 ::
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    restoreState: true
-  }
+    restoreState: true,
+  },
 })
 ```
 
 ## inlineRouteRules
 
-Define route rules at the page level using [`defineRouteRules`](/docs/api/utils/define-route-rules).
+Define route rules at the page level using [`defineRouteRules`](/docs/4.x/api/utils/define-route-rules).
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    inlineRouteRules: true
-  }
+    inlineRouteRules: true,
+  },
 })
 ```
 
 Matching route rules will be created, based on the page's `path`.
 
-::read-more{to="/docs/api/utils/define-route-rules" icon="i-lucide-square-function"}
+::read-more{to="/docs/4.x/api/utils/define-route-rules" icon="i-lucide-square-function"}
 Read more in `defineRouteRules` utility.
 ::
 
-:read-more{to="/docs/guide/concepts/rendering#hybrid-rendering" icon="i-lucide-medal"}
+:read-more{to="/docs/4.x/guide/concepts/rendering#hybrid-rendering" icon="i-lucide-medal"}
 
 ## renderJsonPayloads
 
 Allows rendering of JSON payloads with support for revivifying complex types.
 
-*Enabled by default.*
+This flag is enabled by default, but you can disable this feature:
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    renderJsonPayloads: true
-  }
+    renderJsonPayloads: false,
+  },
 })
 ```
 
@@ -133,8 +217,22 @@ Disables Vue server renderer endpoint within Nitro.
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    noVueServer: true
-  }
+    noVueServer: true,
+  },
+})
+```
+
+## parseErrorData
+
+Whether to parse `error.data` when rendering a server error page.
+
+This flag is enabled by default, but you can disable this feature:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    parseErrorData: false,
+  },
 })
 ```
 
@@ -145,20 +243,20 @@ Enables extraction of payloads of pages generated with `nuxt generate`.
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    payloadExtraction: true
-  }
+    payloadExtraction: true,
+  },
 })
 ```
 
 ## clientFallback
 
-Enables the experimental [`<NuxtClientFallback>`](/docs/api/components/nuxt-client-fallback) component for rendering content on the client if there's an error in SSR.
+Enables the experimental [`<NuxtClientFallback>`](/docs/4.x/api/components/nuxt-client-fallback) component for rendering content on the client if there's an error in SSR.
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    clientFallback: true
-  }
+    clientFallback: true,
+  },
 })
 ```
 
@@ -169,8 +267,8 @@ Enables cross-origin prefetch using the Speculation Rules API.
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    crossOriginPrefetch: true
-  }
+    crossOriginPrefetch: true,
+  },
 })
 ```
 
@@ -185,8 +283,8 @@ Enables View Transition API integration with client-side router.
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    viewTransition: true
-  }
+    viewTransition: true,
+  },
 })
 ```
 
@@ -203,24 +301,24 @@ Enables writing of early hints when using node server.
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    writeEarlyHints: true
-  }
+    writeEarlyHints: true,
+  },
 })
 ```
 
 ## componentIslands
 
-Enables experimental component islands support with [`<NuxtIsland>`](/docs/api/components/nuxt-island) and `.island.vue` files.
+Enables experimental component islands support with [`<NuxtIsland>`](/docs/4.x/api/components/nuxt-island) and `.island.vue` files.
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    componentIslands: true // false or 'local+remote'
-  }
+    componentIslands: true, // false or 'local+remote'
+  },
 })
 ```
 
-:read-more{to="/docs/guide/directory-structure/app/components#server-components"}
+:read-more{to="/docs/4.x/guide/directory-structure/app/components#server-components"}
 
 ::read-more{icon="i-simple-icons-github" to="https://github.com/nuxt/nuxt/issues/19772" target="_blank"}
 You can follow the server components roadmap on GitHub.
@@ -230,13 +328,13 @@ You can follow the server components roadmap on GitHub.
 
 Resolve `~`, `~~`, `@` and `@@` aliases located within layers with respect to their layer source and root directories.
 
-*Enabled by default.*
+This flag is enabled by default, but you can disable this feature:
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    localLayerAliases: true
-  }
+    localLayerAliases: false,
+  },
 })
 ```
 
@@ -247,12 +345,12 @@ Enable the new experimental typed router using [`unplugin-vue-router`](https://g
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    typedPages: true
-  }
+    typedPages: true,
+  },
 })
 ```
 
-Out of the box, this will enable typed usage of [`navigateTo`](/docs/api/utils/navigate-to), [`<NuxtLink>`](/docs/api/components/nuxt-link), [`router.push()`](/docs/api/composables/use-router) and more.
+Out of the box, this will enable typed usage of [`navigateTo`](/docs/4.x/api/utils/navigate-to), [`<NuxtLink>`](/docs/4.x/api/components/nuxt-link), [`router.push()`](/docs/4.x/api/composables/use-router) and more.
 
 You can even get typed params within a page by using `const route = useRoute('route-name')`.
 
@@ -277,8 +375,8 @@ You can also set this to `chokidar` to watch all files in your source directory.
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    watcher: 'chokidar-granular' // 'chokidar' or 'parcel' are also options
-  }
+    watcher: 'chokidar-granular', // 'chokidar' or 'parcel' are also options
+  },
 })
 ```
 
@@ -291,8 +389,8 @@ You can disable this feature if needed.
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    sharedPrerenderData: false
-  }
+    sharedPrerenderData: false,
+  },
 })
 ```
 
@@ -326,7 +424,7 @@ To make globals like `Buffer` work in the browser, you need to manually inject t
 ```ts
 import { Buffer } from 'node:buffer'
 
-globalThis.Buffer = globalThis.Buffer || Buffer
+globalThis.Buffer ||= Buffer
 ```
 ::
 
@@ -343,8 +441,8 @@ You can disable this feature if it causes issues in your project.
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    scanPageMeta: false
-  }
+    scanPageMeta: false,
+  },
 })
 ```
 
@@ -352,11 +450,13 @@ export default defineNuxtConfig({
 
 Enables CookieStore support to listen for cookie updates (if supported by the browser) and refresh `useCookie` ref values.
 
+This flag is enabled by default, but you can disable this feature:
+
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    cookieStore: true
-  }
+    cookieStore: false,
+  },
 })
 ```
 
@@ -368,11 +468,15 @@ Read more about the **CookieStore**.
 
 Caches Nuxt build artifacts based on a hash of the configuration and source files.
 
+This only works for source files within `srcDir` and `serverDir` for the Vue/Nitro parts of your app.
+
+This flag is disabled by default, but you can enable it:
+
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    buildCache: true
-  }
+    buildCache: true,
+  },
 })
 ```
 
@@ -396,6 +500,20 @@ In addition, any changes to files within `srcDir` will trigger a rebuild of the
 A maximum of 10 cache tarballs are kept.
 ::
 
+## checkOutdatedBuildInterval
+
+Set the time interval (in ms) to check for new builds. Disabled when `experimental.appManifest` is `false`.
+
+Set to `false` to disable.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    checkOutdatedBuildInterval: 3600000, // 1 hour, or false to disable
+  },
+})
+```
+
 ## extraPageMetaExtractionKeys
 
 The `definePageMeta()` macro is a useful way to collect build-time meta about pages. Nuxt itself provides a set list of supported keys which is used to power some of the internal features such as redirects, page aliases and custom paths.
@@ -405,7 +523,7 @@ This option allows passing additional keys to extract from the page metadata whe
 ```vue
 <script lang="ts" setup>
 definePageMeta({
-  foo: 'bar'
+  foo: 'bar',
 })
 </script>
 ```
@@ -423,7 +541,23 @@ export default defineNuxtConfig({
 })
 ```
 
-This allows modules to access additional metadata from the page metadata in the build context. If you are using this within a module, it's recommended also to [augment the `NuxtPage` types with your keys](/docs/guide/directory-structure/app/pages#typing-custom-metadata).
+This allows modules to access additional metadata from the page metadata in the build context. If you are using this within a module, it's recommended also to [augment the `NuxtPage` types with your keys](/docs/4.x/guide/directory-structure/app/pages#typing-custom-metadata).
+
+## navigationRepaint
+
+Wait for a single animation frame before navigation, which gives an opportunity for the browser to repaint, acknowledging user interaction.
+
+It can reduce INP when navigating on prerendered routes.
+
+This flag is enabled by default, but you can disable this feature:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    navigationRepaint: false,
+  },
+})
+```
 
 ## normalizeComponentNames
 
@@ -434,8 +568,8 @@ If you encounter issues, you can disable this feature.
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    normalizeComponentNames: false
-  }
+    normalizeComponentNames: false,
+  },
 })
 ```
 
@@ -484,8 +618,8 @@ This is enabled by default in development mode. If you need to disable this feat
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    browserDevtoolsTiming: false
-  }
+    browserDevtoolsTiming: false,
+  },
 })
 ```
 
@@ -508,8 +642,8 @@ To enable it explicitly:
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    debugModuleMutation: true
-  }
+    debugModuleMutation: true,
+  },
 })
 ```
 
@@ -526,26 +660,28 @@ Lazy hydration is enabled by default, but you can disable this feature:
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    lazyHydration: false
-  }
+    lazyHydration: false,
+  },
 })
 ```
 
-::read-more{icon="i-simple-icons-github" color="gray" to="/docs/guide/directory-structure/app/components#delayed-or-lazy-hydration"}
+::read-more{icon="i-simple-icons-github" color="gray" to="/docs/4.x/guide/directory-structure/app/components#delayed-or-lazy-hydration"}
 Read more about lazy hydration.
 ::
 
 ## templateImportResolution
 
-Controls how imports in Nuxt templates are resolved. By default, Nuxt attempts to resolve imports in templates relative to the module that added them.
+Disable resolving imports into Nuxt templates from the path of the module that added the template.
 
-This is enabled by default, so if you're experiencing resolution conflicts in certain environments, you can disable this behavior:
+By default, Nuxt attempts to resolve imports in templates relative to the module that added them. Setting this to `false` disables this behavior, which may be useful if you're experiencing resolution conflicts in certain environments.
+
+This flag is enabled by default, but you can disable this feature:
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    templateImportResolution: false
-  }
+    templateImportResolution: false,
+  },
 })
 ```
 
@@ -553,6 +689,22 @@ export default defineNuxtConfig({
 See PR #31175 for implementation details.
 ::
 
+## templateRouteInjection
+
+By default the route object returned by the auto-imported `useRoute()` composable is kept in sync with the current page in view in `<NuxtPage>`. This is not true for `vue-router`'s exported `useRoute` or for the default `$route` object available in your Vue templates.
+
+By enabling this option a mixin will be injected to keep the `$route` template object in sync with Nuxt's managed `useRoute()`.
+
+This flag is enabled by default, but you can disable this feature:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    templateRouteInjection: false,
+  },
+})
+```
+
 ## decorators
 
 This option enables enabling decorator syntax across your entire Nuxt/Nitro app, powered by [esbuild](https://github.com/evanw/esbuild/releases/tag/v0.21.3).
@@ -591,16 +743,44 @@ const value = new SomeClass().someMethod()
 // this will return 'decorated'
 ```
 
+## defaults
+
+This allows specifying the default options for core Nuxt components and composables.
+
+These options will likely be moved elsewhere in the future, such as into `app.config` or into the `app/` directory.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    defaults: {
+      nuxtLink: {
+        componentName: 'NuxtLink',
+        prefetch: true,
+        prefetchOn: {
+          visibility: true,
+        },
+      },
+      useAsyncData: {
+        deep: true,
+      },
+    },
+  },
+})
+```
+
 ## purgeCachedData
 
-Nuxt will automatically purge cached data from `useAsyncData` and `nuxtApp.static.data`. This helps prevent memory leaks
-and ensures fresh data is loaded when needed, but it is possible to disable it:
+Whether to clean up Nuxt static and asyncData caches on route navigation.
+
+Nuxt will automatically purge cached data from `useAsyncData` and `nuxtApp.static.data`. This helps prevent memory leaks and ensures fresh data is loaded when needed, but it is possible to disable it.
+
+This flag is enabled by default, but you can disable this feature:
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    purgeCachedData: false
-  }
+    purgeCachedData: false,
+  },
 })
 ```
 
@@ -612,11 +792,13 @@ See PR #31379 for implementation details.
 
 Whether to call and use the result from `getCachedData` when refreshing data for `useAsyncData` and `useFetch` (whether by `watch`, `refreshNuxtData()`, or a manual `refresh()` call.
 
+This flag is enabled by default, but you can disable this feature:
+
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    granularCachedData: true
-  }
+    granularCachedData: false,
+  },
 })
 ```
 
@@ -624,17 +806,34 @@ export default defineNuxtConfig({
 See PR #31373 for implementation details.
 ::
 
+## headNext
+
+Use head optimisations:
+
+- Add the capo.js head plugin in order to render tags in of the head in a more performant way.
+- Uses the hash hydration plugin to reduce initial hydration
+
+This flag is enabled by default, but you can disable this feature:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    headNext: false,
+  },
+})
+```
+
 ## pendingWhenIdle
 
-If set to `false`, the `pending` object returned from `useAsyncData`, `useFetch`, `useLazyAsyncData` and `useLazyFetch` will be a computed property that is `true` only when `status` is also pending.
+For `useAsyncData` and `useFetch`, whether `pending` should be `true` when data has not yet started to be fetched.
 
-That means that when `immediate: false` is passed, `pending` will be `false` until the first request is made.
+This flag is disabled by default, but you can enable this feature:
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    pendingWhenIdle: false
-  }
+    pendingWhenIdle: true,
+  },
 })
 ```
 
@@ -659,14 +858,64 @@ If you need to disable this feature you can do so:
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    entryImportMap: false
+    entryImportMap: false,
   },
-// or, better, simply tell vite your desired target
+  // or, better, simply tell vite your desired target
   // which nuxt will respect
   vite: {
     build: {
-      target: 'safari13'
+      target: 'safari13',
     },
   },
 })
 ```
+
+## 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.
+::