@nuxt/docs-nightly 4.1.3-29314777.50febbbb → 4.1.3-29316225.304409da

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

@@ -11,6 +11,36 @@ Internally, Nuxt uses `@nuxt/schema` to define these experimental features. You
 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,
+  },
 })
 ```
 
@@ -61,15 +91,31 @@ This feature will likely be removed in a near future.
 
 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/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.
+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,
+  },
 })
 ```
 
@@ -87,8 +133,8 @@ and consider providing explicit keys to [`useState`](/docs/4.x/api/composables/u
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    restoreState: true
-  }
+    restoreState: true,
+  },
 })
 ```
 
@@ -99,8 +145,8 @@ Define route rules at the page level using [`defineRouteRules`](/docs/4.x/api/ut
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    inlineRouteRules: true
-  }
+    inlineRouteRules: true,
+  },
 })
 ```
 
@@ -116,13 +162,13 @@ Read more in `defineRouteRules` utility.
 
 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 +179,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,8 +205,8 @@ Enables extraction of payloads of pages generated with `nuxt generate`.
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    payloadExtraction: true
-  }
+    payloadExtraction: true,
+  },
 })
 ```
 
@@ -157,8 +217,8 @@ Enables the experimental [`<NuxtClientFallback>`](/docs/4.x/api/components/nuxt-
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    clientFallback: true
-  }
+    clientFallback: true,
+  },
 })
 ```
 
@@ -169,8 +229,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 +245,8 @@ Enables View Transition API integration with client-side router.
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    viewTransition: true
-  }
+    viewTransition: true,
+  },
 })
 ```
 
@@ -203,8 +263,8 @@ Enables writing of early hints when using node server.
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    writeEarlyHints: true
-  }
+    writeEarlyHints: true,
+  },
 })
 ```
 
@@ -215,8 +275,8 @@ Enables experimental component islands support with [`<NuxtIsland>`](/docs/4.x/a
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    componentIslands: true // false or 'local+remote'
-  }
+    componentIslands: true, // false or 'local+remote'
+  },
 })
 ```
 
@@ -230,13 +290,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,8 +307,8 @@ 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,
+  },
 })
 ```
 
@@ -277,8 +337,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 +351,8 @@ You can disable this feature if needed.
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    sharedPrerenderData: false
-  }
+    sharedPrerenderData: false,
+  },
 })
 ```
 
@@ -326,7 +386,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 +403,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 +412,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 +430,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 +462,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 +485,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>
 ```
@@ -425,6 +505,22 @@ 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/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
 
 Nuxt updates auto-generated Vue component names to match the full component name you would use to auto-import the component.
@@ -434,8 +530,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 +580,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 +604,8 @@ To enable it explicitly:
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    debugModuleMutation: true
-  }
+    debugModuleMutation: true,
+  },
 })
 ```
 
@@ -526,8 +622,8 @@ 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,
+  },
 })
 ```
 
@@ -537,15 +633,17 @@ 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 +651,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 +705,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 +754,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 +768,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,13 +820,13 @@ 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',
     },
   },
 })

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

@@ -7,29 +7,51 @@ Some features of Nuxt are available on an opt-in basis, or can be disabled based
 
 ## `features`
 
+### devLogs
+
+Stream server logs to the client as you are developing. These logs can be handled in the `dev:ssr-logs` hook.
+
+By default, this is enabled in development (when test mode is not active).
+
+If set to `silent`, the logs will not be printed to the browser console.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  features: {
+    devLogs: true,
+  },
+})
+```
+
 ### inlineStyles
 
 Inlines styles when rendering HTML. This is currently available only when using Vite.
 
 You can also pass a function that receives the path of a Vue component and returns a boolean indicating whether to inline the styles for that component.
 
+It defaults to `(id) => id.includes('.vue')`.
+
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
   features: {
-    inlineStyles: false // or a function to determine inlining
-  }
+    inlineStyles: false, // or a function to determine inlining
+  },
 })
 ```
 
 ### noScripts
 
-Disables rendering of Nuxt scripts and JS resource hints. Can also be configured granularly within `routeRules`.
+Turn off rendering of Nuxt scripts and JavaScript resource hints. Can also be configured granularly within `routeRules`.
+
+You can also disable scripts more granularly within `routeRules`.
+
+If set to 'production' or `true`, JavaScript will be disabled in production mode only. If set to 'all', JavaScript will be disabled in both development and production modes.
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
   features: {
-    noScripts: true
-  }
+    noScripts: true, // or 'production' | 'all' | false
+  },
 })
 ```
 
@@ -43,19 +65,32 @@ This is used for enabling 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.
 
+### 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.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  future: {
+    multiApp: true,
+  },
+})
+```
+
 ### typescriptBundlerResolution
 
-This enables 'Bundler' module resolution mode for TypeScript, which is the recommended setting
-for frameworks like Nuxt and [Vite](https://vite.dev/guide/performance.html#reduce-resolve-operations).
+This enables 'Bundler' module resolution mode for TypeScript, which is the recommended setting for frameworks like Nuxt and [Vite](https://vite.dev/guide/performance.html#reduce-resolve-operations).
 
 It improves type support when using modern libraries with `exports`.
 
 See [the original TypeScript pull request](https://github.com/microsoft/TypeScript/pull/51669).
 
+You can set it to false to use the legacy 'Node' mode, which is the default for TypeScript.
+
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
   future: {
-    typescriptBundlerResolution: true
-  }
+    typescriptBundlerResolution: false,
+  },
 })
 ```