@nuxt/docs 0.0.0 → 3.17.0

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

@@ -0,0 +1,689 @@
+---
+title: "Experimental Features"
+description: "Enable Nuxt experimental features to unlock new possibilities."
+---
+
+The Nuxt experimental features can be enabled in the Nuxt 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.
+
+::note
+Note that these features are experimental and could be removed or modified in the future.
+::
+
+## 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.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    asyncContext: true
+  }
+})
+```
+
+::read-more{icon="i-simple-icons-github" to="https://github.com/nuxt/nuxt/pull/20918" target="_blank"}
+See full explanation on the GitHub pull-request.
+::
+
+## asyncEntry
+
+Enables generation of an async entry point for the Vue bundle, aiding module federation support.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    asyncEntry: true
+  }
+})
+```
+
+## externalVue
+
+Externalizes `vue`, `@vue/*` and `vue-router` when building.
+
+*Enabled by default.*
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    externalVue: true
+  }
+})
+```
+
+::warning
+This feature will likely be removed in a near future.
+::
+
+## treeshakeClientOnly
+
+Tree shakes contents of client-only components from server bundle.
+
+*Enabled by default.*
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    treeshakeClientOnly: true
+  }
+})
+```
+
+## 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 immediatly, 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/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
+  }
+})
+```
+
+## 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.
+
+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.
+::
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    restoreState: true
+  }
+})
+```
+
+## inlineRouteRules
+
+Define route rules at the page level using [`defineRouteRules`](/docs/api/utils/define-route-rules).
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    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 in `defineRouteRules` utility.
+::
+
+:read-more{to="/docs/guide/concepts/rendering#hybrid-rendering" icon="i-lucide-medal"}
+
+## renderJsonPayloads
+
+Allows rendering of JSON payloads with support for revivifying complex types.
+
+*Enabled by default.*
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    renderJsonPayloads: true
+  }
+})
+```
+
+## noVueServer
+
+Disables Vue server renderer endpoint within Nitro.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    noVueServer: true
+  }
+})
+```
+
+## payloadExtraction
+
+Enables extraction of payloads of pages generated with `nuxt generate`.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    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.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    clientFallback: true
+  }
+})
+```
+
+## crossOriginPrefetch
+
+Enables cross-origin prefetch using the Speculation Rules API.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    crossOriginPrefetch: true
+  }
+})
+```
+
+::read-more{icon="i-simple-icons-w3c" to="https://wicg.github.io/nav-speculation/prefetch.html" target="_blank"}
+Read more about the **Speculation Rules API**.
+::
+
+## viewTransition
+
+Enables View Transition API integration with client-side router.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    viewTransition: true
+  }
+})
+```
+
+:link-example{to="https://stackblitz.com/edit/nuxt-view-transitions?file=app.vue" target="_blank"}
+
+::read-more{icon="i-simple-icons-mdnwebdocs" to="https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API" target="_blank"}
+Read more about the **View Transition API**.
+::
+
+## writeEarlyHints
+
+Enables writing of early hints when using node server.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    writeEarlyHints: true
+  }
+})
+```
+
+## componentIslands
+
+Enables experimental component islands support with [`<NuxtIsland>`](/docs/api/components/nuxt-island) and `.island.vue` files.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    componentIslands: true // false or 'local+remote'
+  }
+})
+```
+
+:read-more{to="/docs/guide/directory-structure/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.
+::
+
+## configSchema
+
+Enables config schema support.
+
+*Enabled by default.*
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    configSchema: true
+  }
+})
+```
+
+## polyfillVueUseHead
+
+Adds a compatibility layer for modules, plugins, or user code relying on the old `@vueuse/head` API.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    polyfillVueUseHead: false
+  }
+})
+```
+
+## respectNoSSRHeader
+
+Allow disabling Nuxt SSR responses by setting the `x-nuxt-no-ssr` header.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    respectNoSSRHeader: false
+  }
+})
+```
+
+## localLayerAliases
+
+Resolve `~`, `~~`, `@` and `@@` aliases located within layers with respect to their layer source and root directories.
+
+*Enabled by default.*
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    localLayerAliases: true
+  }
+})
+```
+
+## typedPages
+
+Enable the new experimental typed router using [`unplugin-vue-router`](https://github.com/posva/unplugin-vue-router).
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    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.
+
+You can even get typed params within a page by using `const route = useRoute('route-name')`.
+
+::important
+If you use `pnpm` without `shamefully-hoist=true`, you will need to have `unplugin-vue-router` installed as a devDependency in order for this feature to work.
+::
+
+:video-accordion{title="Watch a video from Daniel Roe explaining type-safe routing in Nuxt" videoId="SXk-L19gTZk"}
+
+## watcher
+
+Set an alternative watcher that will be used as the watching service for Nuxt.
+
+Nuxt uses `chokidar-granular` by default, which will ignore top-level directories
+(like `node_modules` and `.git`) that are excluded from watching.
+
+You can set this instead to `parcel` to use `@parcel/watcher`, which may improve
+performance in large projects or on Windows platforms.
+
+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
+  }
+})
+```
+
+## sharedPrerenderData
+
+Enabling this feature automatically shares payload *data* between pages that are prerendered. This can result
+in a significant performance improvement when prerendering sites that use `useAsyncData` or `useFetch` and
+fetch the same data in different pages.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    sharedPrerenderData: true
+  }
+})
+```
+
+:video-accordion{title="Watch a video from Alexander Lichter about the experimental sharedPrerenderData" videoId="1jUupYHVvrU"}
+
+It is particularly important when enabling this feature to make sure that any unique key of your data
+is always resolvable to the same data. For example, if you are using `useAsyncData` to fetch
+data related to a particular page, you should provide a key that uniquely matches that data. (`useFetch`
+should do this automatically for you.)
+
+```ts
+// This would be unsafe in a dynamic page (e.g. `[slug].vue`) because the route slug makes a difference
+// to the data fetched, but Nuxt can't know that because it's not reflected in the key.
+const route = useRoute()
+const { data } = await useAsyncData(async () => {
+  return await $fetch(`/api/my-page/${route.params.slug}`)
+})
+// Instead, you should use a key that uniquely identifies the data fetched.
+const { data } = await useAsyncData(route.params.slug, async () => {
+  return await $fetch(`/api/my-page/${route.params.slug}`)
+})
+```
+
+## clientNodeCompat
+
+With this feature, Nuxt will automatically polyfill Node.js imports in the client build using [`unenv`](https://github.com/unjs/unenv).
+
+::note
+To make globals like `Buffer` work in the browser, you need to manually inject them.
+
+```ts
+import { Buffer } from 'node:buffer'
+
+globalThis.Buffer = globalThis.Buffer || Buffer
+```
+::
+
+## scanPageMeta
+
+This option allows exposing some route metadata defined in `definePageMeta` at build-time to modules (specifically `alias`, `name`, `path`, `redirect`, `props` and `middleware`).
+
+This only works with static or strings/arrays rather than variables or conditional assignment. See [original issue](https://github.com/nuxt/nuxt/issues/24770) for more information and context.
+
+It is also possible to scan page metadata only after all routes have been registered in `pages:extend`. Then another hook, `pages:resolved` will be called. To enable this behavior, set `scanPageMeta: 'after-resolve'`.
+
+You can disable this feature if it causes issues in your project.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    scanPageMeta: false
+  }
+})
+```
+
+## cookieStore
+
+Enables CookieStore support to listen for cookie updates (if supported by the browser) and refresh `useCookie` ref values.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    cookieStore: true
+  }
+})
+```
+
+::read-more{icon="i-simple-icons-mdnwebdocs" to="https://developer.mozilla.org/en-US/docs/Web/API/CookieStore" target="_blank"}
+Read more about the **CookieStore**.
+::
+
+## buildCache
+
+Caches Nuxt build artifacts based on a hash of the configuration and source files.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    buildCache: true
+  }
+})
+```
+
+When enabled, changes to the following files will trigger a full rebuild:
+
+```bash [Directory structure]
+.nuxtrc
+.npmrc
+package.json
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+tsconfig.json
+bun.lockb
+```
+
+In addition, any changes to files within `srcDir` will trigger a rebuild of the Vue client/server bundle. Nitro will always be rebuilt (though work is in progress to allow Nitro to announce its cacheable artifacts and their hashes).
+
+::note
+A maximum of 10 cache tarballs are kept.
+::
+
+## 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.
+
+This option allows passing additional keys to extract from the page metadata when using `scanPageMeta`.
+
+```vue
+<script lang="ts" setup>
+definePageMeta({
+  foo: 'bar'
+})
+</script>
+```
+
+```ts
+export default defineNuxtConfig({
+  experimental: {
+    extraPageMetaExtractionKeys: ['foo'],
+  },
+  hooks: {
+    'pages:resolved' (ctx) {
+      // ✅ foo is available
+    },
+  },
+})
+```
+
+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/pages#typing-custom-metadata).
+
+## normalizeComponentNames
+
+Ensure that auto-generated Vue component names match the full component name
+you would use to auto-import the component.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    normalizeComponentNames: true
+  }
+})
+```
+
+By default, if you haven't set it manually, Vue will assign a component name that matches
+the filename of the component.
+
+```bash [Directory structure]
+├─ components/
+├─── SomeFolder/
+├───── MyComponent.vue
+```
+
+In this case, the component name would be `MyComponent`, as far as Vue is concerned. If you wanted to use `<KeepAlive>` with it, or identify it in the Vue DevTools, you would need to use this component.
+
+But in order to auto-import it, you would need to use `SomeFolderMyComponent`.
+
+By setting `experimental.normalizeComponentNames`, these two values match, and Vue will generate a component name that matches the Nuxt pattern for component naming.
+
+## spaLoadingTemplateLocation
+
+When rendering a client-only page (with `ssr: false`), we optionally render a loading screen (from `app/spa-loading-template.html`).
+
+It can be set to `within`, which will render it like this:
+
+```html
+<div id="__nuxt">
+  <!-- spa loading template -->
+</div>
+```
+
+Alternatively, you can render the template alongside the Nuxt app root by setting it to `body`:
+
+```html
+<div id="__nuxt"></div>
+<!-- spa loading template -->
+```
+
+This avoids a white flash when hydrating a client-only page.
+
+## browserDevtoolsTiming
+
+Enables performance markers for Nuxt hooks in browser devtools. This adds performance markers that you can track in the Performance tab of Chromium-based browsers, which is useful for debugging and optimizing performance.
+
+This is enabled by default in development mode. If you need to disable this feature, it is possible to do so:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    browserDevtoolsTiming: false
+  }
+})
+```
+
+::read-more{icon="i-simple-icons-github" color="gray" to="https://github.com/nuxt/nuxt/pull/29922" target="_blank"}
+See PR #29922 for implementation details.
+::
+
+::read-more{icon="i-simple-icons-googlechrome" color="gray" to="https://developer.chrome.com/docs/devtools/performance/extension#tracks" target="_blank"}
+Learn more about Chrome DevTools Performance API.
+::
+
+## debugModuleMutation
+
+Records mutations to `nuxt.options` in module context, helping to debug configuration changes made by modules during the Nuxt initialization phase.
+
+This is enabled by default when `debug` mode is enabled. If you need to disable this feature, it is possible to do so:
+
+To enable it explicitly:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    debugModuleMutation: true
+  }
+})
+```
+
+::read-more{icon="i-simple-icons-github" color="gray" to="https://github.com/nuxt/nuxt/pull/30555" target="_blank"}
+See PR #30555 for implementation details.
+::
+
+## lazyHydration
+
+This enables hydration strategies for `<Lazy>` components, which improves performance by deferring hydration of components until they're needed.
+
+Lazy hydration is enabled by default, but you can disable this feature:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    lazyHydration: false
+  }
+})
+```
+
+::read-more{icon="i-simple-icons-github" color="gray" to="/docs/guide/directory-structure/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.
+
+This is enabled by default, so if you're experiencing resolution conflicts in certain environments, you can disable this behavior:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    templateImportResolution: false
+  }
+})
+```
+
+::read-more{icon="i-simple-icons-github" color="gray" to="https://github.com/nuxt/nuxt/pull/31175" target="_blank"}
+See PR #31175 for implementation details.
+::
+
+## 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).
+
+For a long time, TypeScript has had support for decorators via `compilerOptions.experimentalDecorators`. This implementation predated the TC39 standardization process. Now, decorators are a [Stage 3 Proposal](https://github.com/tc39/proposal-decorators), and supported without special configuration in TS 5.0+ (see https://github.com/microsoft/TypeScript/pull/52582 and https://devblogs.microsoft.com/typescript/announcing-typescript-5-0-beta/#decorators).
+
+Enabling `experimental.decorators` enables support for the TC39 proposal, **NOT** for TypeScript's previous `compilerOptions.experimentalDecorators` implementation.
+
+::warning
+Note that there may be changes before this finally lands in the JS standard.
+::
+
+### Usage
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    decorators: true,
+  },
+})
+```
+
+```ts [app.vue]
+function something (_method: () => unknown) {
+  return () => 'decorated'
+}
+
+class SomeClass {
+  @something
+  public someMethod () {
+    return 'initial'
+  }
+}
+
+const value = new SomeClass().someMethod()
+// this will return 'decorated'
+```
+
+## 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:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    purgeCachedData: false
+  }
+})
+```
+
+::read-more{icon="i-simple-icons-github" color="gray" to="https://github.com/nuxt/nuxt/pull/31379" target="_blank"}
+See PR #31379 for implementation details.
+::
+
+## granularCachedData
+
+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.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    granularCachedData: true
+  }
+})
+```
+
+::read-more{icon="i-simple-icons-github" color="gray" to="https://github.com/nuxt/nuxt/pull/31373" target="_blank"}
+See PR #31373 for implementation details.
+::
+
+## 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.
+
+That means that when `immediate: false` is passed, `pending` will be `false` until the first request is made.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    pendingWhenIdle: false
+  }
+})
+```