general-reference

388 notes in this subject, read out of this brain and free to use. This is page 5 of 7.

cookieStore experimental feature

The `cookieStore` experimental feature 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 can be disabled by setting `experimental.cookieStore: false` in the config.

buildCache experimental feature

The `buildCache` experimental feature 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 the app. This flag is disabled by default and can be enabled by setting `experimental.buildCache: true` in the config. When enabled, changes to `.nuxtrc`, `.npmrc`, `package.json`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `tsconfig.json`, `bun.lock`, and `bun.lockb` files will trigger a full rebuild. Any changes to files within `srcDir` trigger a rebuild of the Vue client/server bundle. Nitro is always rebuilt. A maximum of 10 cache tarballs are kept.

checkOutdatedBuildInterval experimental feature

The `checkOutdatedBuildInterval` experimental feature sets the time interval in milliseconds to check for new builds. It is disabled when `experimental.appManifest` is `false`. It can be set to `false` to disable the feature. For example, setting it to `3600000` checks every 1 hour, or it can be disabled by setting to `false`.

extraPageMetaExtractionKeys experimental feature

The `extraPageMetaExtractionKeys` experimental feature allows passing additional keys to extract from the page metadata when using `scanPageMeta`. This enables modules to access additional metadata from the page metadata in the build context. If using this within a module, it is recommended to augment the `NuxtPage` types with the custom keys. Keys are provided as an array string.

extractSerializablePageMeta experimental feature

The `extractSerializablePageMeta` experimental feature is enabled by default when `future.compatibilityVersion` is set to 5 or higher. By default, Nuxt only reads a fixed list of `definePageMeta()` keys at build time (plus anything in `extraPageMetaExtractionKeys`). With this option enabled, Nuxt writes every JSON-serializable property straight into the generated route record instead. When every property of a page's `definePageMeta()` can be resolved statically, the route no longer imports that page's meta module, which removes one module per page from the dev module graph. Properties whose values cannot be serialized (functions, variable references, spreads, computed keys) are unaffected and still resolved at runtime. This feature has no effect when `scanPageMeta` is false. It can be disabled by setting `experimental.extractSerializablePageMeta: false` in the config.

navigationRepaint experimental feature

The `navigationRepaint` experimental feature waits for a single animation frame before navigation, which gives an opportunity for the browser to repaint and acknowledge user interaction. It can reduce INP when navigating on prerendered routes. This flag is enabled by default but can be disabled by setting `experimental.navigationRepaint: false` in the config.

normalizeComponentNames experimental feature

The `normalizeComponentNames` experimental feature updates auto-generated Vue component names to match the full component name used for auto-importing the component. By default, Vue assigns a component name that matches the filename, but auto-importing uses the full folder path. This feature makes these two values match. For example, a component at `components/SomeFolder/MyComponent.vue` would have the auto-import name `SomeFolderMyComponent`, and with this feature enabled, Vue generates a component name that matches this pattern. It can be disabled by setting `experimental.normalizeComponentNames: false` in the config.

normalizePageNames experimental feature

The `normalizePageNames` experimental feature ensures that page component names match their route names by setting the `__name` property on page components. This allows Vue's `<KeepAlive>` to correctly identify pages by name. By default, Vue assigns component names based on the filename, so multiple pages with the same filename (like `pages/foo/index.vue` and `pages/bar/index.vue`) would both have the component name `index`. With this feature enabled, page components are named after their route (e.g., `foo` and `bar`), making name-based `<KeepAlive>` filtering reliable without manually adding `defineOptions({ name: '...' })` to each page. This flag is enabled when `future.compatibilityVersion` is set to 5 or higher, but can be disabled by setting `experimental.normalizePageNames: false` in the config.

spaLoadingTemplateLocation experimental feature

The `spaLoadingTemplateLocation` experimental feature controls where the SPA loading template is rendered when rendering a client-only page (with `ssr: false`). It can be set to `'within'` (default), which renders the loading template inside the `<div id="__nuxt">` root, or `'body'`, which renders it alongside the Nuxt app root. Setting it to `'body'` avoids a white flash when hydrating a client-only page. The template is loaded from `~/spa-loading-template.html`.

browserDevtoolsTiming experimental feature

The `browserDevtoolsTiming` experimental feature enables performance markers for Nuxt hooks in browser devtools. This adds performance markers that can be tracked in the Performance tab of Chromium-based browsers, useful for debugging and optimizing performance. This is enabled by default in development mode but can be disabled by setting `experimental.browserDevtoolsTiming: false` in the config.

debugModuleMutation experimental feature

The `debugModuleMutation` experimental feature 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. It can be enabled explicitly by setting `experimental.debugModuleMutation: true` in the config.

lazyHydration experimental feature

The `lazyHydration` experimental feature enables hydration strategies for `<Lazy>` components, which improves performance by deferring hydration of components until they are needed. Lazy hydration is enabled by default but can be disabled by setting `experimental.lazyHydration: false` in the config.

templateImportResolution experimental feature

The `templateImportResolution` experimental feature controls whether Nuxt resolves imports in templates relative to the module that added them. This flag is enabled by default but can be disabled by setting `experimental.templateImportResolution: false` in the config. Disabling this behavior may be useful if experiencing resolution conflicts in certain environments.

templateRouteInjection experimental feature

The `templateRouteInjection` experimental feature controls whether the route object returned by the auto-imported `useRoute()` composable is kept in sync with the current page in view in `<NuxtPage>`. By default, this is not true for `vue-router`'s exported `useRoute` or for the default `$route` object available in Vue templates. By enabling this option, a mixin is injected to keep the `$route` template object in sync with Nuxt's managed `useRoute()`. This flag is enabled by default but can be disabled by setting `experimental.templateRouteInjection: false` in the config.

decorators experimental feature

The `decorators` experimental feature enables decorator syntax across the entire Nuxt/Nitro app. When using the Vite builder (default), decorators are lowered via Babel using `@babel/plugin-proposal-decorators`. When using webpack or rspack builders, decorators are lowered via esbuild. This enables support for the TC39 Stage 3 Proposal for decorators, NOT for TypeScript's previous `compilerOptions.experimentalDecorators` implementation. Note that there may be changes before this finally lands in the JS standard. When using the Vite builder or Nitro server build, additional Babel packages must be installed as dev dependencies: `@babel/plugin-proposal-decorators` and `@babel/plugin-syntax-jsx`. Nuxt will prompt to install these automatically if not already present.

defaults experimental feature

The `defaults` experimental feature 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. Options can be set for `nuxtLink` (with properties like `componentName`, `prefetch`, `prefetchOn`), `useAsyncData` (with properties like `deep`), and `useState` (with properties like `resetOnClear`). The `useState.resetOnClear` option controls whether `clearNuxtState` resets state to its initial value or sets it to undefined, and defaults to true with `compatibilityVersion: 5`.

purgeCachedData experimental feature

The `purgeCachedData` experimental feature controls whether to clean up Nuxt static and asyncData caches on route navigation. Nuxt automatically purges cached data from `useAsyncData` and `nuxtApp.static.data`, helping prevent memory leaks and ensuring fresh data is loaded when needed. This flag is enabled by default but can be disabled by setting `experimental.purgeCachedData: false` in the config.

Sourcemaps enabled by default

Sourcemaps are enabled for the server build by default, and for the client build in dev mode.

Configure sourcemaps in Nuxt config

Sourcemaps can be configured more specifically using the defineNuxtConfig function with a sourcemap object containing server and client boolean properties.

Sourcemap configuration example

Example showing how to enable sourcemaps for both server and client: export default defineNuxtConfig({ sourcemap: { server: true, client: true, }, })

VS Code debug configuration for Nuxt

VS Code debug configuration requires three parts: a Chrome client configuration pointing to http://localhost:3000 with webRoot set to ${workspaceFolder}/app (the default srcDir), a Node server configuration running ${workspaceFolder}/node_modules/nuxt/bin/nuxt.mjs with 'dev' argument, and a compound configuration named 'fullstack: nuxt' that runs both configurations together.

VS Code Chrome debug configuration with browser extensions

To use browser extensions in VS Code debugging, add 'userDataDir': false to the Chrome configuration.

JetBrains IDEs debug configuration for Nuxt

JetBrains IDEs (IntelliJ IDEA, WebStorm, PhpStorm) can debug Nuxt apps using a configuration file named nuxt.run.xml in the project root. This file contains three configurations: a JavaScript debug configuration for Chrome client pointing to http://localhost:3000, a Node.js configuration for the server pointing to $PROJECT_DIR$/node_modules/nuxt/bin/nuxt.mjs with 'dev' argument, and a compound configuration that runs both.

Node Inspector platform requirement

Node.js and Chrome processes need to be run on the same platform when using Node Inspector. This does not work inside Docker.

Debug Nuxt server-side with Node Inspector

Use Node Inspector to debug Nuxt server-side by running 'nuxt dev --inspect'. This starts Nuxt in dev mode with the debugger active. A Node.js icon will appear in Chrome DevTools when everything is working correctly, allowing you to attach to the debugger.

NuxtLayout with named slots example

Example of using named slots with NuxtLayout. In pages/index.vue: ```vue <template> <div> <NuxtLayout name="custom"> <template #header> Some header template content. </template> </NuxtLayout> </div> </template> ``` In app/layouts/custom.vue, receive the slot: ```vue <template> <div> <slot name="header" /> <slot /> </div> </template> ```

NuxtLayout component purpose

The <NuxtLayout /> component activates layouts on pages and error pages. You can use it in app.vue or error.vue to render layouts.

NuxtLayout name prop

The name prop specifies which layout to render. It accepts a string, reactive reference, or computed property. It must match the name of a layout file in the app/layouts/ directory, or false to disable the layout. Type: string | false. Default: 'default'.

NuxtLayout fallback prop

The fallback prop specifies a layout to render if an invalid layout is passed to the name prop. It must match the name of a layout file in the app/layouts/ directory. Type: string. Default: null.

NuxtLayout additional props

NuxtLayout accepts any additional custom props beyond name and fallback. These props are made accessible as attributes in the layout component using $attrs in templates or useAttrs() in script setup.

NuxtLayout transitions with slot

NuxtLayout renders content via <slot /> wrapped in Vue's <Transition /> component to activate layout transitions. For this to work properly, NuxtLayout should not be the root element of the page component.

Accessing layout ref

To get a reference to a layout component, access it through ref.value.layoutRef. The layout component must expose methods using defineExpose() to make them available to the parent.

NuxtLayout basic usage example

Basic usage of NuxtLayout in app.vue: ```vue <template> <NuxtLayout> some page content </NuxtLayout> </template> ``` This activates the default layout.

Dynamic layout name example

Example of using a dynamic layout name in pages/index.vue: ```vue <script setup lang="ts"> const layout = 'custom' </script> <template> <NuxtLayout :name="layout"> <NuxtPage /> </NuxtLayout> </template> ```

Layout with custom props example

Example of passing custom props to a layout in pages/some-page.vue: ```vue <template> <div> <NuxtLayout name="custom" title="I am a custom layout" >  </NuxtLayout> </div> </template> ``` In the layout component, access the prop using useAttrs().title or $attrs.title.

Layout ref access example

Example of accessing layout ref in app/app.vue: ```vue <script setup lang="ts"> const layout = ref() function logFoo () { layout.value.layoutRef.foo() } </script> <template> <NuxtLayout ref="layout"> default layout </NuxtLayout> </template> ``` In app/layouts/default.vue, expose methods: ```vue <script setup lang="ts"> const foo = () => console.log('foo') defineExpose({ foo, }) </script> <template> <div> default layout <slot /> </div> </template> ```

useNuxtApp.ssrContext property available on server side only

ssrContext is generated during server-side rendering and is only available on the server side. Nuxt exposes the following properties through ssrContext: url (string) for the current request URL, event (h3js/h3 request event) to access the request and response of the current route, and payload (object) which is the NuxtApp payload object.

useNuxtApp.vueApp property accesses Vue application instance

The vueApp property is the global Vue.js application instance accessible through nuxtApp. It provides useful methods: component() for registering or retrieving global components, directive() for registering or retrieving global custom directives, and use() for installing Vue.js Plugins.

useNuxtApp composable for accessing Nuxt runtime context

useNuxtApp is a built-in composable that provides access to the shared runtime context of Nuxt, known as the Nuxt context. It is available on both client and server side but not within Nitro routes. It helps you access the Vue app instance, runtime hooks, runtime config variables, and internal states such as ssrContext and payload.

useNuxtApp throws exception when runtime context unavailable

If runtime context is unavailable in your scope, useNuxtApp will throw an exception when called. Use tryUseNuxtApp instead for composables that do not require nuxtApp, or to check if context is available without an exception.

Vue Composition API context behavior in async operations

The Composition API depends on implicit context that Vue sets as a temporary instance in a global variable during the lifecycle and unsets it in the same tick. When async operations occur, Vue unsets the global instance before the async call, making getCurrentInstance() and Nuxt composables unavailable after await. This is a design limitation of composables. Vue's `<script setup>` compiler transform restores context after each call, allowing composables to work. Nuxt applies similar transforms to defineNuxtPlugin() and defineNuxtRouteMiddleware() to enable context restoration.

tryUseNuxtApp returns null instead of throwing exception

tryUseNuxtApp (available since Nuxt v3.10) works exactly the same as useNuxtApp but returns null if context is unavailable instead of throwing an exception. It can be used for composables that do not require nuxtApp, or to check if context is available without throwing an exception.

useNuxtApp.runWithContext() restores Nuxt context in async scenarios

The runWithContext method is meant to be used to call a function and give it an explicit Nuxt context. It is used in complex async/await scenarios in middleware/plugins where the current instance has been unset after an async call, such as in try/catch blocks. The method restores context automatically, similar to how `<script setup>` works. It accepts a function that requires Nuxt context and returns whatever the function returns.

useNuxtApp.isHydrating property checks hydration state

Use nuxtApp.isHydrating (boolean) to check if the Nuxt app is currently hydrating on the client side. This is useful for conditional logic during hydration.

Custom reducer and reviver for payload serialization (Nuxt v3.4+)

Since Nuxt v3.4, you can define custom reducer/reviver for types not supported by Nuxt using payload plugins with definePayloadPlugin. The reducer is a serializer called on the server side, and the reviver is a deserializer called on the client side. The type identifier string must be the same for both the reducer and reviver. Payload plugins run very early in the Nuxt lifecycle before payload revival, and do not have access to router or other Nuxt-injected properties.

useNuxtApp.payload property exposes server-to-client data

The payload property exposes data and state variables from server side to client side. It contains: serverRendered (boolean) indicating if response is server-side-rendered, data (object) containing cached API fetch results from useFetch or useAsyncData that are accessible via payload.data to prevent refetching, and state (object) containing shared state created with useState composable accessible via payload.state.[name-of-your-state].

NuxtClientFallback props reference

NuxtClientFallback has the following props: placeholderTag or fallbackTag (type: string, default: 'div') to specify a fallback tag to be rendered if the slot fails to render on the server; placeholder or fallback (type: string) to specify fallback content to be rendered if the slot fails to render; keepFallback (type: boolean, default: false) to keep the fallback content if it failed to render server-side.

NuxtClientFallback XSS security warning

The placeholder and fallback props render content as raw HTML. Do not pass untrusted user input to these props as it may lead to XSS vulnerabilities. Use the #fallback or #placeholder slots instead for dynamic content that needs proper escaping.

NuxtClientFallback example with fallback content

Example of NuxtClientFallback with fallback-tag and fallback props: ```vue <template> <NuxtClientFallback fallback-tag="span" fallback="Hello world" > <BrokeInSSR /> </NuxtClientFallback> </template> ``` This renders <span>Hello world</span> server-side if the default slot fails to render.

NuxtClientFallback example with fallback slot

Example of NuxtClientFallback with #fallback slot: ```vue <template> <NuxtClientFallback>  <template #fallback> <p>Hello world</p> </template> </NuxtClientFallback> </template> ``` The fallback slot content renders on server side if the default slot fails to render in SSR.

NuxtClientFallback component purpose

The NuxtClientFallback component renders its content on the client if any of its children trigger an error in SSR. This component is experimental and requires enabling the experimental.clientFallback option in nuxt.config.

NuxtClientFallback ssr-error event

The NuxtClientFallback component emits an @ssr-error event when a child triggers an error in SSR. This event is only triggered on the server.

NuxtClientFallback slots reference

NuxtClientFallback provides a #fallback slot to specify content to be displayed server-side if the default slot fails to render.

NuxtPicture component purpose

NuxtPicture is a drop-in replacement for the native picture tag that handles automatic image optimization and allows serving modern formats like webp when possible.

NuxtPicture similarity to NuxtImg

Usage of NuxtPicture is almost identical to NuxtImg, with the additional capability of serving modern formats like webp.

NuxtRouteAnnouncer component purpose

The NuxtRouteAnnouncer component adds a hidden element with the page title to announce route changes to assistive technologies. It is available in Nuxt v3.12 and later.

NuxtRouteAnnouncer placement in app.vue

NuxtRouteAnnouncer should be added in app.vue or app/layouts/ to enhance accessibility by informing assistive technologies about page title changes. It should wrap NuxtLayout and NuxtPage components.

NuxtRouteAnnouncer props and defaults

NuxtRouteAnnouncer has two props: 'atomic' (boolean, default false) controls if screen readers announce only changes (false) or entire content (true) on updates; 'politeness' (string, default 'polite') sets screen reader announcement urgency with values 'off' (disable), 'polite' (wait for silence), or 'assertive' (interrupt immediately).

NuxtRouteAnnouncer slot with message

NuxtRouteAnnouncer accepts a default slot that receives a 'message' variable containing the announcement text. This allows custom HTML or components to be passed through the route announcer.

useRouteAnnouncer composable

The useRouteAnnouncer composable allows you to hook into the underlying announcer instance and set a custom announcement message.

Give your agent this brain