2023-06-20 18:17:07 +00:00
---
title: "Experimental Features"
2023-10-18 10:59:43 +00:00
description: "Enable Nuxt experimental features to unlock new possibilities."
2023-06-20 18:17:07 +00:00
---
The Nuxt experimental features can be enabled in the Nuxt configuration file.
2023-10-18 10:59:43 +00:00
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.
::callout
2023-06-20 18:17:07 +00:00
Note that these features are experimental and could be removed or modified in the future.
::
2023-09-19 20:24:02 +00:00
## asyncContext
2023-10-18 10:59:43 +00:00
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.
2023-09-19 20:24:02 +00:00
```ts [nuxt.config.ts]
2023-10-18 10:59:43 +00:00
export defineNuxtConfig({
experimental: {
asyncContext: true
}
})
2023-09-19 20:24:02 +00:00
```
2023-10-18 10:59:43 +00:00
::read-more{icon="i-simple-icons-github" color="gray" to="https://github.com/nuxt/nuxt/pull/20918" target="_blank"}
See full explanation on the GitHub pull-request.
::
2023-06-20 18:17:07 +00:00
## asyncEntry
Enables generation of an async entry point for the Vue bundle, aiding module federation support.
```ts [nuxt.config.ts]
2023-10-18 10:59:43 +00:00
export defineNuxtConfig({
experimental: {
asyncEntry: true
}
})
2023-06-20 18:17:07 +00:00
```
## externalVue
Externalizes `vue` , `@vue/*` and `vue-router` when building.
2023-10-18 10:59:43 +00:00
2023-06-20 18:17:07 +00:00
*Enabled by default.*
```ts [nuxt.config.ts]
2023-10-18 10:59:43 +00:00
export defineNuxtConfig({
experimental: {
externalVue: true
}
})
2023-06-20 18:17:07 +00:00
```
2023-10-18 10:59:43 +00:00
::callout{color="amber" icon="i-ph-warning-duotone"}
This feature will likely be removed in a near future.
2023-06-20 18:17:07 +00:00
::
## treeshakeClientOnly
Tree shakes contents of client-only components from server bundle.
2023-10-18 10:59:43 +00:00
2023-06-20 18:17:07 +00:00
*Enabled by default.*
```ts [nuxt.config.ts]
2023-10-18 10:59:43 +00:00
export defineNuxtConfig({
experimental: {
treeshakeClientOnly: true
}
})
2023-06-20 18:17:07 +00:00
```
## emitRouteChunkError
Emits `app:chunkError` hook when there is an error loading vite/webpack chunks. Default behavior is to perform a hard reload of the new route when a chunk fails to load.
2023-10-18 10:59:43 +00:00
2023-06-20 18:17:07 +00:00
You can disable automatic handling by setting this to `false` , or handle chunk errors manually by setting it to `manual` .
```ts [nuxt.config.ts]
2023-10-18 10:59:43 +00:00
export defineNuxtConfig({
experimental: {
emitRouteChunkError: 'automatic' // or 'manual' or false
}
})
2023-06-20 18:17:07 +00:00
```
## restoreState
2023-10-18 10:59:43 +00:00
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.
2023-06-20 18:17:07 +00:00
2023-10-18 10:59:43 +00:00
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.
::callout{color="amber" icon="i-ph-warning-duotone"}
2023-06-20 18:17:07 +00:00
Consider carefully before enabling this as it can cause unexpected behavior,
2023-07-07 16:24:09 +00:00
and consider providing explicit keys to [`useState` ](/docs/api/composables/use-state ) as auto-generated keys may not match across builds.
2023-06-20 18:17:07 +00:00
::
```ts [nuxt.config.ts]
2023-10-18 10:59:43 +00:00
export defineNuxtConfig({
experimental: {
restoreState: true
}
})
2023-06-20 18:17:07 +00:00
```
2023-10-18 10:59:43 +00:00
## inlineRouteRules
Define route rules at the page level using [`defineRouteRules` ](/docs/api/utils/define-route-rules ).
```ts [nuxt.config.ts]
export 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-ph-function-duotone"}
Read more in `defineRouteRules` utility.
::
:read-more{to="/docs/guide/concepts/rendering#hybrid-rendering" icon="i-ph-medal-duotone"}
2023-06-20 18:17:07 +00:00
## inlineSSRStyles
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.
```ts [nuxt.config.ts]
2023-10-18 10:59:43 +00:00
export defineNuxtConfig({
experimental: {
inlineSSRStyles: true // or a function to determine inlining
}
})
2023-06-20 18:17:07 +00:00
```
## noScripts
Disables rendering of Nuxt scripts and JS resource hints. Can also be configured granularly within `routeRules` .
```ts [nuxt.config.ts]
2023-10-18 10:59:43 +00:00
export defineNuxtConfig({
experimental: {
noScripts: true
}
})
2023-06-20 18:17:07 +00:00
```
## renderJsonPayloads
Allows rendering of JSON payloads with support for revivifying complex types.
2023-10-18 10:59:43 +00:00
2023-06-20 18:17:07 +00:00
*Enabled by default.*
```ts [nuxt.config.ts]
2023-10-18 10:59:43 +00:00
export defineNuxtConfig({
experimental: {
renderJsonPayloads: true
}
})
2023-06-20 18:17:07 +00:00
```
## noVueServer
Disables Vue server renderer endpoint within Nitro.
```ts [nuxt.config.ts]
2023-10-18 10:59:43 +00:00
export defineNuxtConfig({
experimental: {
noVueServer: true
}
})
2023-06-20 18:17:07 +00:00
```
## payloadExtraction
Enables extraction of payloads of pages generated with `nuxt generate` .
```ts [nuxt.config.ts]
2023-10-18 10:59:43 +00:00
export defineNuxtConfig({
experimental: {
payloadExtraction: true
}
})
2023-06-20 18:17:07 +00:00
```
## clientFallback
2023-10-18 10:59:43 +00:00
Enables the experimental [`<NuxtClientFallback>` ](/docs/api/components/nuxt-client-fallback ) component for rendering content on the client if there's an error in SSR.
2023-06-20 18:17:07 +00:00
```ts [nuxt.config.ts]
2023-10-18 10:59:43 +00:00
export defineNuxtConfig({
experimental: {
clientFallback: true
}
})
2023-06-20 18:17:07 +00:00
```
## crossOriginPrefetch
Enables cross-origin prefetch using the Speculation Rules API.
```ts [nuxt.config.ts]
2023-10-18 10:59:43 +00:00
export defineNuxtConfig({
experimental: {
crossOriginPrefetch: true
}
})
2023-06-20 18:17:07 +00:00
```
2023-10-18 10:59:43 +00:00
::read-more{icon="i-simple-icons-w3c" color="gray" to="https://wicg.github.io/nav-speculation/prefetch.html" target="_blank"}
Read more about the **Speculation Rules API** .
::
2023-06-20 18:17:07 +00:00
## viewTransition
Enables View Transition API integration with client-side router.
```ts [nuxt.config.ts]
2023-10-18 10:59:43 +00:00
export defineNuxtConfig({
experimental: {
viewTransition: true
}
})
2023-06-20 18:17:07 +00:00
```
2023-10-18 10:59:43 +00:00
:link-example{to="https://stackblitz.com/edit/nuxt-view-transitions?file=app.vue" target="_blank"}
::read-more{icon="i-simple-icons-mdnwebdocs" color="gray" to="https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API" target="_blank"}
Read more about the **View Transition API** .
2023-08-08 15:11:32 +00:00
::
2023-06-20 18:17:07 +00:00
## writeEarlyHints
Enables writing of early hints when using node server.
```ts [nuxt.config.ts]
2023-10-18 10:59:43 +00:00
export defineNuxtConfig({
experimental: {
writeEarlyHints: true
}
})
2023-06-20 18:17:07 +00:00
```
## componentIslands
2023-10-18 10:59:43 +00:00
Enables experimental component islands support with [`<NuxtIsland>` ](/docs/api/components/nuxt-island ) and `.island.vue` files.
2023-06-20 18:17:07 +00:00
```ts [nuxt.config.ts]
2023-10-18 10:59:43 +00:00
export defineNuxtConfig({
experimental: {
componentIslands: true // false or 'local+remote'
}
})
2023-06-20 18:17:07 +00:00
```
2023-10-18 10:59:43 +00:00
:read-more{to="/docs/guide/directory-structure/components#server-components"}
2023-06-20 18:17:07 +00:00
2023-10-18 10:59:43 +00:00
::read-more{icon="i-simple-icons-github" color="gray" to="https://github.com/nuxt/nuxt/issues/19772" target="_blank"}
You can follow the server components roadmap on GitHub.
::
2023-06-20 18:17:07 +00:00
## configSchema
Enables config schema support.
2023-10-18 10:59:43 +00:00
2023-06-20 18:17:07 +00:00
*Enabled by default.*
```ts [nuxt.config.ts]
2023-10-18 10:59:43 +00:00
export defineNuxtConfig({
experimental: {
configSchema: true
}
})
2023-06-20 18:17:07 +00:00
```
## polyfillVueUseHead
Adds a compatibility layer for modules, plugins, or user code relying on the old `@vueuse/head` API.
```ts [nuxt.config.ts]
2023-10-18 10:59:43 +00:00
export defineNuxtConfig({
experimental: {
polyfillVueUseHead: false
}
})
2023-06-20 18:17:07 +00:00
```
## respectNoSSRHeader
Allow disabling Nuxt SSR responses by setting the `x-nuxt-no-ssr` header.
```ts [nuxt.config.ts]
2023-10-18 10:59:43 +00:00
export defineNuxtConfig({
experimental: {
respectNoSSRHeader: false
}
})
2023-06-20 18:17:07 +00:00
```
## localLayerAliases
Resolve `~` , `~~` , `@` and `@@` aliases located within layers with respect to their layer source and root directories.
2023-10-18 10:59:43 +00:00
2023-06-20 18:17:07 +00:00
*Enabled by default.*
```ts [nuxt.config.ts]
2023-10-18 10:59:43 +00:00
export defineNuxtConfig({
experimental: {
localLayerAliases: true
}
})
2023-06-20 18:17:07 +00:00
```
## typedPages
2023-10-18 10:59:43 +00:00
Enable the new experimental typed router using [`unplugin-vue-router` ](https://github.com/posva/unplugin-vue-router ).
2023-06-20 18:17:07 +00:00
```ts [nuxt.config.ts]
2023-10-18 10:59:43 +00:00
export defineNuxtConfig({
experimental: {
2023-11-23 20:48:06 +00:00
typedPages: true
2023-10-18 10:59:43 +00:00
}
})
2023-06-20 18:17:07 +00:00
```
2023-10-18 10:59:43 +00:00
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.
2023-06-20 18:17:07 +00:00
You can even get typed params within a page by using `const route = useRoute('route-name')` .
## watcher
Set an alternative watcher that will be used as the watching service for Nuxt.
2023-10-18 10:59:43 +00:00
2023-06-20 18:17:07 +00:00
Nuxt uses `chokidar-granular` by default, which will ignore top-level directories
(like `node_modules` and `.git` ) that are excluded from watching.
2023-10-18 10:59:43 +00:00
2023-06-20 18:17:07 +00:00
You can set this instead to `parcel` to use `@parcel/watcher` , which may improve
performance in large projects or on Windows platforms.
2023-10-18 10:59:43 +00:00
2023-06-20 18:17:07 +00:00
You can also set this to `chokidar` to watch all files in your source directory.
```ts [nuxt.config.ts]
export defineNuxtConfig({
2023-10-18 10:59:43 +00:00
experimental: {
watcher: 'chokidar-granular' // 'chokidar' or 'parcel' are also options
}
2023-06-20 18:17:07 +00:00
})
```