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 52432aadaf..e0135f1310 100644 --- a/docs/2.guide/3.going-further/1.experimental-features.md +++ b/docs/2.guide/3.going-further/1.experimental-features.md @@ -529,6 +529,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 38aa343f29..629f5ac7c1 100644 --- a/packages/schema/src/config/experimental.ts +++ b/packages/schema/src/config/experimental.ts @@ -623,14 +623,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) => { @@ -640,6 +672,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) => { @@ -649,6 +704,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, },