Experimental Features
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 or the source code for more information.
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.
export default defineNuxtConfig({
experimental: {
asyncContext: true
}
})
asyncEntry
Enables generation of an async entry point for the Vue bundle, aiding module federation support.
export default defineNuxtConfig({
experimental: {
asyncEntry: true
}
})
externalVue
Externalizes vue, @vue/* and vue-router when building.
Enabled by default.
export default defineNuxtConfig({
experimental: {
externalVue: true
}
})
treeshakeClientOnly
Tree shakes contents of client-only components from server bundle.
Enabled by default.
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. 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.
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() 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.
useState as auto-generated keys may not match across builds.export default defineNuxtConfig({
experimental: {
restoreState: true
}
})
inlineRouteRules
Define route rules at the page level using defineRouteRules.
export default defineNuxtConfig({
experimental: {
inlineRouteRules: true
}
})
Matching route rules will be created, based on the page's path.
renderJsonPayloads
Allows rendering of JSON payloads with support for revivifying complex types.
Enabled by default.
export default defineNuxtConfig({
experimental: {
renderJsonPayloads: true
}
})
noVueServer
Disables Vue server renderer endpoint within Nitro.
export default defineNuxtConfig({
experimental: {
noVueServer: true
}
})
payloadExtraction
Enables extraction of payloads of pages generated with nuxt generate.
export default defineNuxtConfig({
experimental: {
payloadExtraction: true
}
})
clientFallback
Enables the experimental <NuxtClientFallback> component for rendering content on the client if there's an error in SSR.
export default defineNuxtConfig({
experimental: {
clientFallback: true
}
})
crossOriginPrefetch
Enables cross-origin prefetch using the Speculation Rules API.
export default defineNuxtConfig({
experimental: {
crossOriginPrefetch: true
}
})
viewTransition
Enables View Transition API integration with client-side router.
export default defineNuxtConfig({
experimental: {
viewTransition: true
}
})
writeEarlyHints
Enables writing of early hints when using node server.
export default defineNuxtConfig({
experimental: {
writeEarlyHints: true
}
})
componentIslands
Enables experimental component islands support with <NuxtIsland> and .island.vue files.
export default defineNuxtConfig({
experimental: {
componentIslands: true // false or 'local+remote'
}
})
configSchema
Enables config schema support.
Enabled by default.
export default defineNuxtConfig({
experimental: {
configSchema: true
}
})
polyfillVueUseHead
Adds a compatibility layer for modules, plugins, or user code relying on the old @vueuse/head API.
export default defineNuxtConfig({
experimental: {
polyfillVueUseHead: false
}
})
respectNoSSRHeader
Allow disabling Nuxt SSR responses by setting the x-nuxt-no-ssr header.
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.
export default defineNuxtConfig({
experimental: {
localLayerAliases: true
}
})
typedPages
Enable the new experimental typed router using unplugin-vue-router.
export default defineNuxtConfig({
experimental: {
typedPages: true
}
})
Out of the box, this will enable typed usage of navigateTo, <NuxtLink>, router.push() and more.
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.
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.
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.
export default defineNuxtConfig({
experimental: {
sharedPrerenderData: true
}
})
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.)
// 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.
Buffer work in the browser, you need to manually inject them.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).
This only works with static or strings/arrays rather than variables or conditional assignment. See original issue 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.
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.
export default defineNuxtConfig({
experimental: {
cookieStore: true
}
})
buildCache
Caches Nuxt build artifacts based on a hash of the configuration and source files.
export default defineNuxtConfig({
experimental: {
buildCache: true
}
})
When enabled, changes to the following files will trigger a full rebuild:
.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).
normalizeComponentNames
Ensure that auto-generated Vue component names match the full component name you would use to auto-import the component.
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.
├─ 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.