`. This fixes a Vue hydration issue where scoped styles may not be applied when the placeholder `
` and the actual component root share the same tag name.
Enabling this means attributes (`class`, `style`, etc.) passed to `.client.vue` components will not appear in the SSR HTML. If you need styled placeholders to prevent layout shift, use `` with a `#fallback` slot instead.
This flag is enabled when `future.compatibilityVersion` is set to `5` or higher, but you can also enable it explicitly:
```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
clientNodePlaceholder: true,
},
})
```
## clientFallback
Enables the experimental [`
`](/docs/4.x/api/components/nuxt-client-fallback) component for rendering content on the client if there's an error in SSR.
```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
clientFallback: true,
},
})
```
## crossOriginPrefetch
Enables cross-origin prefetch using the Speculation Rules API.
```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
crossOriginPrefetch: true,
},
})
```
Read more about the **Speculation Rules API**.
## viewTransition
Enables View Transition API integration with client-side router.
```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
viewTransition: true,
},
})
```
You can also pass an object to configure [view transition types](/docs/4.x/getting-started/transitions#view-transition-types), which allow different CSS animations based on the type of navigation:
```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
viewTransition: {
enabled: true,
types: ['slide'],
},
},
})
```
Read more about the **View Transition API**.
Read more about the **View Transition API**.
## writeEarlyHints
Enables writing of early hints when using node server.
```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
writeEarlyHints: true,
},
})
```
## componentIslands
Enables experimental component islands support with [``](/docs/4.x/api/components/nuxt-island) and `.island.vue` files.
```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
componentIslands: true, // false or 'local+remote'
},
})
```
You can follow the server components roadmap on GitHub.
## localLayerAliases
Resolve `~`, `~~`, `@` and `@@` aliases located within layers with respect to their layer source and root directories.
This flag is enabled by default, but you can disable this feature:
```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
localLayerAliases: false,
},
})
```
## typedPages
Enable the new experimental typed router.
```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
typedPages: true,
},
})
```
Out of the box, this will enable typed usage of [`navigateTo`](/docs/4.x/api/utils/navigate-to), [``](/docs/4.x/api/components/nuxt-link), [`router.push()`](/docs/4.x/api/composables/use-router) 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.
```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
watcher: 'chokidar-granular', // 'chokidar' or 'parcel' are also options
},
})
```
## sharedPrerenderData
Nuxt 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.
You can disable this feature if needed.
```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
sharedPrerenderData: false,
},
})
```
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 (_nuxtApp, { signal }) => {
return await $fetch(`/api/my-page/${route.params.slug}`, { signal })
})
// Instead, you should use a key that uniquely identifies the data fetched.
const { data } = await useAsyncData(route.params.slug, async (_nuxtApp, { signal }) => {
return await $fetch(`/api/my-page/${route.params.slug}`, { signal })
})
```
## clientNodeCompat
With this feature, Nuxt will automatically polyfill Node.js imports in the client build using [`unenv`](https://github.com/unjs/unenv).
To make globals like `Buffer` work in the browser, you need to manually inject them.
```ts
import { Buffer } from 'node:buffer'
globalThis.Buffer ||= Buffer
```
## scanPageMeta
Nuxt 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.
By default page metadata is only scanned after all routes have been registered in `pages:extend`. Then another hook, `pages:resolved` will be called.
You can disable this feature if it causes issues in your project.
```ts [nuxt.config.ts]twoslash
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.
This flag is enabled by default, but you can disable this feature:
```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
cookieStore: false,
},
})
```
Read more about the **CookieStore**.
## buildCache
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 [nuxt.config.ts]twoslash
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.lock
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).
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 [nuxt.config.ts]twoslash
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.
This option allows passing additional keys to extract from the page metadata when using `scanPageMeta`.
```vue
```
```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/4.x/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 [nuxt.config.ts]twoslash
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.
If you encounter issues, you can disable this feature.
```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
normalizeComponentNames: false,
},
})
```
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 `` 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.
## normalizePageNames
Ensure that page component names match their route names. This sets the `__name` property on page components so that Vue's `` can correctly identify them by name.
By default, Vue assigns component names based on the filename. For example, `pages/foo/index.vue` and `pages/bar/index.vue` would both have the component name `index`. This makes name-based `` filtering unreliable because multiple pages share the same name.
With `normalizePageNames` enabled, page components are named after their route (e.g. `foo` and `bar`), so you can use `` with `include`/`exclude` without manually adding `defineOptions({ name: '...' })` to each page.
This flag is enabled when `future.compatibilityVersion` is set to `5` or higher, but you can disable this feature:
```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
normalizePageNames: false,
},
})
```
```vue [app.vue]
```
## spaLoadingTemplateLocation
When rendering a client-only page (with `ssr: false`), we optionally render a loading screen (from `~/spa-loading-template.html`).
It can be set to `within`, which will render it like this:
```html
```
Alternatively, you can render the template alongside the Nuxt app root by setting it to `body`:
```html
```
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 [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
browserDevtoolsTiming: false,
},
})
```
See PR #29922 for implementation details.
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 [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
debugModuleMutation: true,
},
})
```
See PR #30555 for implementation details.
## lazyHydration
This enables hydration strategies for `` 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 [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
lazyHydration: false,
},
})
```
Read more about lazy hydration.
## templateImportResolution
Disable resolving imports into Nuxt templates from the path of the module that added the template.
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 [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
templateImportResolution: false,
},
})
```
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 ``. 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 [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
templateRouteInjection: false,
},
})
```
## decorators
This option enables decorator syntax across your entire Nuxt/Nitro app.
When using the Vite builder (default), decorators are lowered via [Babel](https://babeljs.io/) using [`@babel/plugin-proposal-decorators`](https://babeljs.io/docs/babel-plugin-proposal-decorators). When using the webpack or rspack builders, decorators are lowered via [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](https://github.com/microsoft/TypeScript/pull/52582) and [https://devblogs.microsoft.com/typescript/announcing-typescript-5-0-beta/#decorators](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.
Note that there may be changes before this finally lands in the JS standard.
### Usage
```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
decorators: true,
},
})
```
When using the Vite builder or the Nitro server build, you will need to install additional Babel packages as dev dependencies:
```bash [npm]
npm install -D @babel/plugin-proposal-decorators @babel/plugin-syntax-jsx
```
```bash [pnpm]
pnpm add -D @babel/plugin-proposal-decorators @babel/plugin-syntax-jsx
```
```bash [yarn]
yarn add -D @babel/plugin-proposal-decorators @babel/plugin-syntax-jsx
```
Nuxt will prompt you to install these automatically if they are not already present.
```ts [app/app.vue]
function something (_method: () => unknown) {
return () => 'decorated'
}
class SomeClass {
@something
public someMethod () {
return 'initial'
}
}
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 [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
defaults: {
nuxtLink: {
componentName: 'NuxtLink',
prefetch: true,
prefetchOn: {
visibility: true,
},
},
useAsyncData: {
deep: true,
},
useState: {
resetOnClear: true,
},
},
},
})
```
The `useState.resetOnClear` option controls whether [`clearNuxtState`](/docs/4.x/api/utils/clear-nuxt-state) resets state to its initial value (provided by the `init` function of [`useState`](/docs/4.x/api/composables/use-state)) instead of setting it to `undefined`. This defaults to `true` with `compatibilityVersion: 5`.
## purgeCachedData
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 [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
purgeCachedData: false,
},
})
```
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.
This flag is enabled by default, but you can disable this feature:
```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
granularCachedData: false,
},
})
```
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 [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
headNext: false,
},
})
```
## pendingWhenIdle
For `useAsyncData` and `useFetch`, whether `pending` should be `true` when data has not yet started to be fetched.
This flag is disabled by default, but you can enable this feature:
```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
pendingWhenIdle: true,
},
})
```
## entryImportMap
By default, Nuxt improves chunk stability by using an import map to resolve the entry chunk of the bundle.
This injects an import map at the top of your `` tag:
```html
```
Within the script chunks emitted by Vite, imports will be from `#entry`. This means that changes to the entry will not invalidate chunks which are otherwise unchanged.
Nuxt smartly disables this feature if you have configured `vite.build.target` to include a browser that doesn't support import maps, or if you have configured `vite.build.rollupOptions.output.entryFileNames` to a value that does not include `[hash]`.
If you need to disable this feature you can do so:
```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
entryImportMap: false,
},
// or, better, simply tell vite your desired target
// which nuxt will respect
vite: {
build: {
target: 'safari13',
},
},
})
```
## typescriptPlugin
Enable enhanced TypeScript developer experience with the `@dxup/nuxt` module.
This experimental plugin provides improved TypeScript integration and development tooling for better DX when working with TypeScript in Nuxt applications.
This flag is disabled by default, but you can enable this feature:
```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
typescriptPlugin: true,
},
})
```
To use this feature, you need to:
- Have `typescript` installed as a dependency
- Configure VS Code to use your workspace TypeScript version (see [VS Code documentation](https://code.visualstudio.com/docs/typescript/typescript-compiling#_using-the-workspace-version-of-typescript))
Learn more about **@dxup/nuxt**.
## viteEnvironmentApi
Enable Vite 6's new [Environment API](https://vite.dev/guide/api-environment) for improved build configuration and plugin architecture.
When you set `future.compatibilityVersion` to `5`, this feature is enabled by default. You can also enable it explicitly for testing:
```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
viteEnvironmentApi: true,
},
})
```
The Vite Environment API provides better consistency between development and production builds, more granular control over environment-specific configuration, and improved performance.
Enabling this feature changes how Vite plugins are registered and configured. See the [Vite Environment API migration guide](/docs/4.x/getting-started/upgrade#migration-to-vite-environment-api) for details on updating your plugins.
Learn more about Vite's Environment API.