diff --git a/docs/1.getting-started/12.upgrade.md b/docs/1.getting-started/12.upgrade.md index 750c255763..da4b3179da 100644 --- a/docs/1.getting-started/12.upgrade.md +++ b/docs/1.getting-started/12.upgrade.md @@ -224,6 +224,31 @@ export default defineNuxtConfig({ }) ``` +#### Deduplication of Route Metadata + +🚦 **Impact Level**: Minimal + +##### What Changed + +It's possible to set some route metadata using `definePageMeta`, such as the `name`, `path`, and so on. Previously these were available both on the route and on route metadata (for example, `route.name` and `route.meta.name`). + +Now, they are only accessible on the route object. + +##### Reasons for Change + +This is a result of enabling `experimental.scanPageMeta` by default, and is a performance optimization. + +##### Migration Steps + +The migration should be straightforward: + +```diff + const route = useRoute() + +- console.log(route.meta.name) ++ console.log(route.name) +``` + #### Normalized Component Names 🚦 **Impact Level**: Moderate diff --git a/docs/2.guide/3.going-further/1.experimental-features.md b/docs/2.guide/3.going-further/1.experimental-features.md index 1f7f33bf51..5431240b29 100644 --- a/docs/2.guide/3.going-further/1.experimental-features.md +++ b/docs/2.guide/3.going-further/1.experimental-features.md @@ -477,6 +477,84 @@ Alternatively, you can render the template alongside the Nuxt app root by settin 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 twoslash [nuxt.config.ts] +export default defineNuxtConfig({ + experimental: { + browserDevtoolsTiming: false + } +}) +``` + +::read-more{icon="i-simple-icons-github" color="gray" to="https://github.com/nuxt/nuxt/pull/29922" target="_blank"} +See PR #29922 for implementation details. +:: + +::read-more{icon="i-simple-icons-googlechrome" color="gray" to="https://developer.chrome.com/docs/devtools/performance/extension#tracks" target="_blank"} +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 twoslash [nuxt.config.ts] +export default defineNuxtConfig({ + experimental: { + debugModuleMutation: true + } +}) +``` + +::read-more{icon="i-simple-icons-github" color="gray" to="https://github.com/nuxt/nuxt/pull/30555" target="_blank"} +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 twoslash [nuxt.config.ts] +export default defineNuxtConfig({ + experimental: { + lazyHydration: false + } +}) +``` + +::read-more{icon="i-simple-icons-github" color="gray" to="/docs/guide/directory-structure/components#delayed-or-lazy-hydration"} +Read more about lazy hydration. +:: + +## templateImportResolution + +Controls how imports in Nuxt templates are resolved. By default, Nuxt attempts to resolve imports in templates relative to the module that added them. + +This is enabled by default, so if you're experiencing resolution conflicts in certain environments, you can disable this behavior: + +```ts twoslash [nuxt.config.ts] +export default defineNuxtConfig({ + experimental: { + templateImportResolution: false + } +}) +``` + +::read-more{icon="i-simple-icons-github" color="gray" to="https://github.com/nuxt/nuxt/pull/31175" target="_blank"} +See PR #31175 for implementation details. +:: + ## decorators This option enables enabling decorator syntax across your entire Nuxt/Nitro app, powered by [esbuild](https://github.com/evanw/esbuild/releases/tag/v0.21.3). diff --git a/packages/schema/src/config/experimental.ts b/packages/schema/src/config/experimental.ts index aef9df1d28..cf5cb65a8d 100644 --- a/packages/schema/src/config/experimental.ts +++ b/packages/schema/src/config/experimental.ts @@ -464,14 +464,46 @@ export default defineResolvers({ /** * Enable timings for Nuxt application hooks in the performance panel of Chromium-based browsers. * - * @see [the Chrome DevTools extensibility API](https://developer.chrome.com/docs/devtools/performance/extension#tracks) + * This feature adds performance markers for Nuxt hooks, allowing you to track their execution time + * in the browser's Performance tab. This is particularly useful for debugging performance issues. + * + * @example + * ```ts + * // nuxt.config.ts + * export default defineNuxtConfig({ + * experimental: { + * // Enable performance markers for Nuxt hooks in browser devtools + * browserDevtoolsTiming: true + * } + * }) + * ``` + * + * @see [PR #29922](https://github.com/nuxt/nuxt/pull/29922) + * @see [Chrome DevTools Performance API](https://developer.chrome.com/docs/devtools/performance/extension#tracks) */ browserDevtoolsTiming: { $resolve: async (val, get) => typeof val === 'boolean' ? val : await get('dev'), }, /** - * Record mutations to `nuxt.options` in module context + * Record mutations to `nuxt.options` in module context, helping to debug configuration changes + * made by modules during the Nuxt initialization phase. + * + * When enabled, Nuxt will track which modules modify configuration options, making it + * easier to trace unexpected configuration changes. + * + * @example + * ```ts + * // nuxt.config.ts + * export default defineNuxtConfig({ + * experimental: { + * // Enable tracking of config mutations by modules + * debugModuleMutation: true + * } + * }) + * ``` + * + * @see [PR #30555](https://github.com/nuxt/nuxt/pull/30555) */ debugModuleMutation: { $resolve: async (val, get) => { @@ -481,6 +513,29 @@ export default defineResolvers({ /** * Enable automatic configuration of hydration strategies for `` components. + * + * This feature intelligently determines when to hydrate lazy components based on + * visibility, idle time, or other triggers, improving performance by deferring + * hydration of components until they're needed. + * + * @example + * ```ts + * // nuxt.config.ts + * export default defineNuxtConfig({ + * experimental: { + * lazyHydration: true // Enable smart hydration strategies for Lazy components + * } + * }) + * + * // In your Vue components + * + * ``` + * + * @see [PR #26468](https://github.com/nuxt/nuxt/pull/26468) */ lazyHydration: { $resolve: (val) => { @@ -490,6 +545,23 @@ export default defineResolvers({ /** * 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. + * + * @example + * ```ts + * // nuxt.config.ts + * export default defineNuxtConfig({ + * experimental: { + * // Disable template import resolution from module path + * templateImportResolution: false + * } + * }) + * ``` + * + * @see [PR #31175](https://github.com/nuxt/nuxt/pull/31175) */ templateImportResolution: true, },