@nuxt/docs-nightly 4.4.0-29533707.0a5a5c19 → 4.4.0-29533953.9698f387

package/1.getting-started/18.upgrade.md

@@ -59,6 +59,7 @@ export default defineNuxtConfig({
 When you set your `future.compatibilityVersion` to `5`, defaults throughout your Nuxt configuration will change to opt in to Nuxt v5 behavior, including:
 
 - **Vite Environment API**: Automatically enables the new [Vite Environment API](/docs/4.x/getting-started/upgrade#migration-to-vite-environment-api) for improved build configuration
+- **Normalized Page Names**: Page component names will [match their route names](/docs/4.x/getting-started/upgrade#normalized-page-component-names) for consistent `<KeepAlive>` behavior
 - **`clearNuxtState` resets to defaults**: `clearNuxtState` will [reset state to its initial value](/docs/4.x/getting-started/upgrade#respect-defaults-when-clearing-usestate) instead of setting it to `undefined`
 - Other Nuxt 5 improvements and changes as they become available
 
@@ -1374,6 +1375,41 @@ export default defineNuxtConfig({
 Read more about Nitro's prerender configuration options.
 ::
 
+### Normalized Page Component Names
+
+🚦 **Impact Level**: Minimal
+
+#### What Changed
+
+When `future.compatibilityVersion` is set to `5` (or `experimental.normalizePageNames` is enabled), page component names match their route names instead of using the filename. For example, `pages/foo/index.vue` will have the component name `foo` instead of `index`.
+
+#### Reasons for Change
+
+Previously, Vue assigned component names based on the filename. This meant multiple pages like `pages/foo/index.vue` and `pages/bar/index.vue` would both have the component name `index`. This made `<KeepAlive>` with `include`/`exclude` filters unreliable and required manually adding `defineOptions({ name: '...' })` to each page.
+
+#### Migration Steps
+
+If you rely on the current component names (e.g. in `<KeepAlive>` `include`/`exclude` lists), update them to use route names instead of filenames.
+
+```diff
+<template>
+  <NuxtPage :keepalive="{
+-   include: ['index']
++   include: ['foo']
+  }" />
+</template>
+```
+
+To disable this behavior:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    normalizePageNames: false,
+  },
+})
+```
+
 ## Nuxt 2 vs. Nuxt 3+
 
 In the table below, there is a quick comparison between 3 versions of Nuxt:

package/3.guide/6.going-further/1.experimental-features.md

@@ -607,6 +607,30 @@ 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 `<KeepAlive>` 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 `<KeepAlive>` 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 `<KeepAlive>` 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 twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    normalizePageNames: false,
+  },
+})
+```
+
+```vue [app.vue]
+<template>
+  <NuxtPage :keepalive="{ include: ['foo'] }" />
+</template>
+```
+
 ## spaLoadingTemplateLocation
 
 When rendering a client-only page (with `ssr: false`), we optionally render a loading screen (from `~/spa-loading-template.html`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "4.4.0-29533707.0a5a5c19",
+  "version": "4.4.0-29533953.9698f387",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",