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 defineNuxtConfig({
  experimental: {
    asyncContext: true
  }
})

asyncEntry

Enables generation of an async entry point for the Vue bundle, aiding module federation support.

export defineNuxtConfig({
  experimental: {
    asyncEntry: true
  }
})

externalVue

Externalizes vue, @vue/* and vue-router when building.

Enabled by default.

export defineNuxtConfig({
  experimental: {
    externalVue: true
  }
})

treeshakeClientOnly

Tree shakes contents of client-only components from server bundle.

Enabled by default.

export defineNuxtConfig({
  experimental: {
    treeshakeClientOnly: true
  }
})

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.

You can disable automatic handling by setting this to false, or handle chunk errors manually by setting it to manual.

export defineNuxtConfig({
  experimental: {
    emitRouteChunkError: 'automatic' // or '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.

export defineNuxtConfig({
  experimental: {
    restoreState: true
  }
})

inlineRouteRules

Define route rules at the page level using defineRouteRules.

export 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 defineNuxtConfig({
  experimental: {
    renderJsonPayloads: true
  }
})

noVueServer

Disables Vue server renderer endpoint within Nitro.

export defineNuxtConfig({
  experimental: {
    noVueServer: true
  }
})

payloadExtraction

Enables extraction of payloads of pages generated with nuxt generate.

export defineNuxtConfig({
  experimental: {
    payloadExtraction: true
  }
})

clientFallback

Enables the experimental <NuxtClientFallback> component for rendering content on the client if there's an error in SSR.

export defineNuxtConfig({
  experimental: {
    clientFallback: true
  }
})

crossOriginPrefetch

Enables cross-origin prefetch using the Speculation Rules API.

export defineNuxtConfig({
  experimental: {
    crossOriginPrefetch: true
  }
})

viewTransition

Enables View Transition API integration with client-side router.

export defineNuxtConfig({
  experimental: {
    viewTransition: true
  }
})

writeEarlyHints

Enables writing of early hints when using node server.

export defineNuxtConfig({
  experimental: {
    writeEarlyHints: true
  }
})

componentIslands

Enables experimental component islands support with <NuxtIsland> and .island.vue files.

export defineNuxtConfig({
  experimental: {
    componentIslands: true // false or 'local+remote'
  }
})

configSchema

Enables config schema support.

Enabled by default.

export defineNuxtConfig({
  experimental: {
    configSchema: true
  }
})

polyfillVueUseHead

Adds a compatibility layer for modules, plugins, or user code relying on the old @vueuse/head API.

export defineNuxtConfig({
  experimental: {
    polyfillVueUseHead: false
  }
})

respectNoSSRHeader

Allow disabling Nuxt SSR responses by setting the x-nuxt-no-ssr header.

export defineNuxtConfig({
  experimental: {
    respectNoSSRHeader: false
  }
})

localLayerAliases

Resolve ~, ~~, @ and @@ aliases located within layers with respect to their layer source and root directories.

Enabled by default.

export defineNuxtConfig({
  experimental: {
    localLayerAliases: true
  }
})

typedPages

Enable the new experimental typed router using unplugin-vue-router.

export 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 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 defineNuxtConfig({ 
  experimental: { 
    sharedPrerenderData: true
  } 
})

Note that by default Nuxt will render pages concurrently, meaning this does not guarantee that data will not be fetched more than once.

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.

import { Buffer } from 'node:buffer'

globalThis.Buffer = globalThis.Buffer || Buffer