feat(nuxt,schema): experimentally normalise page component names to match route by huang-julien · Pull Request #33513 · nuxt/nuxt

huang-julien · 2025-10-18T17:40:42Z

📚 Description

resolves #33254

this PR adds an experimental feature to normalize page components names using the route name.

bolt-new-by-stackblitz · 2025-10-18T17:40:45Z

Run & review this pull request in StackBlitz Codeflow.

packages/nuxt/src/pages/utils.ts

pkg-pr-new · 2025-10-18T17:44:47Z

Open in StackBlitz

@nuxt/kit

npm i https://pkg.pr.new/@nuxt/kit@33513

@nuxt/nitro-server

npm i https://pkg.pr.new/@nuxt/nitro-server@33513

nuxt

npm i https://pkg.pr.new/nuxt@33513

@nuxt/rspack-builder

npm i https://pkg.pr.new/@nuxt/rspack-builder@33513

@nuxt/schema

npm i https://pkg.pr.new/@nuxt/schema@33513

@nuxt/vite-builder

npm i https://pkg.pr.new/@nuxt/vite-builder@33513

@nuxt/webpack-builder

npm i https://pkg.pr.new/@nuxt/webpack-builder@33513

commit: 7e5b326

codspeed-hq · 2025-10-18T17:56:04Z

Merging this PR will not alter performance

✅ 20 untouched benchmarks
⏩ 3 skipped benchmarks¹

_{Comparing feat/33254 (7e5b326) with main (0a5a5c1)}

3 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

coderabbitai · 2025-10-20T19:18:34Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 9f3f2a8 and 7e5b326.

📒 Files selected for processing (2)

docs/1.getting-started/18.upgrade.md
docs/3.guide/6.going-further/1.experimental-features.md

Walkthrough

Adds an experimental option experimental.normalizePageNames (resolvable default based on future.compatibilityVersion) to the config schema. normalizeRoutes now retrieves Nuxt context via useNuxt(), computes isSyncImport per page and, when normalizePageNames is enabled, assigns a __name to page components by wrapping synchronous imports with Object.assign or chaining .then on dynamic imports. Tests and documentation were added or adjusted for the feature.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main feature: adding experimental normalisation of page component names to match route names, which is the primary change in this PR.
Description check	✅ Passed	The description is related to the changeset, referencing issue `#33254` and explaining the experimental feature for normalising page component names using route names.
Linked Issues check	✅ Passed	The PR fully addresses issue `#33254` by implementing automatic assignment of route names as page component names, enabling keep-alive and similar features to work without requiring manual defineOptions in each page.
Out of Scope Changes check	✅ Passed	All changes are in scope: core implementation in packages/nuxt, configuration schema additions in packages/schema, comprehensive tests, and documentation updates aligned with the feature objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch feat/33254

Tip

Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs).
Share your feedback on Discord.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

danielroe · 2025-10-21T08:46:12Z

packages/nuxt/src/pages/utils.ts

            : pageImport,
      }

+      if (nuxt.options.experimental.normalizePageNames) {


could we maybe split this into normalizeComponent and normalizeComponentWithName functions, so we only assign it once, rather than manipulating an existing string?

Do you mean a normalizeComponentName at runtime ?

no. I mean, at the moment it's created a few lines above and then changed here

we can instead create it just once, which will tidy up the logic

packages/nuxt/src/pages/utils.ts

# Conflicts: # packages/nuxt/src/pages/utils.ts # packages/nuxt/test/__snapshots__/pages-override-meta-enabled.test.ts.snap # packages/nuxt/test/pages.test.ts # test/bundle.test.ts

packages/nuxt/src/pages/utils.ts

danielroe

nice one ❤️

packages/nuxt/src/pages/utils.ts

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/1.getting-started/18.upgrade.md`:
- Around line 1332-1342: Update the "What Changed" and "Migration Steps" text to
clarify this behavior is conditional: mention that page component names change
only when the opt-in flags are enabled (experimental.normalizePageNames or
future.compatibilityVersion: 5). Edit the "What Changed" paragraph and the
Migration Steps sentence to explicitly state the change applies only if
experimental.normalizePageNames is true or future.compatibilityVersion is set to
5, and advise users to enable that flag or check their compatibilityVersion
before updating KeepAlive include/exclude lists.

In `@docs/3.guide/6.going-further/1.experimental-features.md`:
- Line 618: The wording is ambiguous—replace the short key
"compatibilityVersion" with the fully-qualified config key
"future.compatibilityVersion" in the sentence that currently reads
"compatibilityVersion is set to 5 or higher" so the docs explicitly reference
future.compatibilityVersion and avoid confusion with similarly named options.

ℹ️ Review info

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ef39e42 and 810193e.

📒 Files selected for processing (2)

docs/1.getting-started/18.upgrade.md
docs/3.guide/6.going-further/1.experimental-features.md

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

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

# Conflicts: # docs/1.getting-started/18.upgrade.md

coderabbitai

♻️ Duplicate comments (2)

docs/3.guide/6.going-further/1.experimental-features.md (1)

618-618: ⚠️ Potential issue | 🟡 Minor

Use the fully-qualified config key in the default-behaviour sentence.

At Line 618, compatibilityVersion is ambiguous; this should explicitly reference future.compatibilityVersion.

Suggested fix

-This flag is enabled when `compatibilityVersion` is set to `5` or higher, but you can disable this feature:
+This flag is enabled when `future.compatibilityVersion` is set to `5` or higher, but you can disable this feature:

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/3.guide/6.going-further/1.experimental-features.md` at line 618, The
sentence currently refers to `compatibilityVersion` ambiguously; update the
default-behaviour sentence so it uses the fully-qualified config key
`future.compatibilityVersion` instead of the short form, e.g., change
"compatibilityVersion is set to 5 or higher" to "future.compatibilityVersion is
set to 5 or higher" in the paragraph that starts with "This flag is enabled when
...".

docs/1.getting-started/18.upgrade.md (1)

1384-1392: ⚠️ Potential issue | 🟠 Major

Scope this migration note to opt-in/compat mode.

At Lines 1384-1392, the text reads as unconditional, but this behaviour is conditional. Please state that it applies when experimental.normalizePageNames is enabled or when future.compatibilityVersion is 5.

Suggested wording update

-Page component names now match their route names instead of using the filename. For example, `pages/foo/index.vue` will have the component name `foo` instead of `index`.
+When `experimental.normalizePageNames` is enabled (or when `future.compatibilityVersion` is set to `5`), 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`.

-If you rely on the current component names (e.g. in `<KeepAlive>` `include`/`exclude` lists), update them to use route names instead of filenames.
+If you enable this behaviour and rely on current component names (e.g. in `<KeepAlive>` `include`/`exclude` lists), update them to use route names instead of filenames.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/1.getting-started/18.upgrade.md` around lines 1384 - 1392, Update the
migration note titled "Page component names now match their route names..." to
make the change conditional: state explicitly that this behavior only applies
when experimental.normalizePageNames is enabled or when
future.compatibilityVersion is set to 5 (compat mode). Replace the unconditional
sentences in the "Reasons for Change" / "Migration Steps" block with wording
that scopes the behavior to those config flags and add a short migration tip
advising users to update <KeepAlive> include/exclude lists to use route names
when opting into experimental.normalizePageNames or running in
future.compatibilityVersion: 5.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In `@docs/1.getting-started/18.upgrade.md`:
- Around line 1384-1392: Update the migration note titled "Page component names
now match their route names..." to make the change conditional: state explicitly
that this behavior only applies when experimental.normalizePageNames is enabled
or when future.compatibilityVersion is set to 5 (compat mode). Replace the
unconditional sentences in the "Reasons for Change" / "Migration Steps" block
with wording that scopes the behavior to those config flags and add a short
migration tip advising users to update <KeepAlive> include/exclude lists to use
route names when opting into experimental.normalizePageNames or running in
future.compatibilityVersion: 5.

In `@docs/3.guide/6.going-further/1.experimental-features.md`:
- Line 618: The sentence currently refers to `compatibilityVersion` ambiguously;
update the default-behaviour sentence so it uses the fully-qualified config key
`future.compatibilityVersion` instead of the short form, e.g., change
"compatibilityVersion is set to 5 or higher" to "future.compatibilityVersion is
set to 5 or higher" in the paragraph that starts with "This flag is enabled when
...".

ℹ️ Review info

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 810193e and 9f3f2a8.

📒 Files selected for processing (4)

docs/1.getting-started/18.upgrade.md
docs/3.guide/6.going-further/1.experimental-features.md
packages/schema/src/config/experimental.ts
packages/schema/src/types/schema.ts

🚧 Files skipped from review as they are similar to previous changes (1)

packages/schema/src/types/schema.ts

huang-julien added 2 commits October 18, 2025 19:15

feat(nuxt): experimental page component name normalisation

86ccc94

test: update

ef39e42

huang-julien requested a review from danielroe as a code owner October 18, 2025 17:40

huang-julien marked this pull request as draft October 18, 2025 17:40

github-actions bot added 4.x enhancement labels Oct 18, 2025

github-advanced-security bot found potential problems Oct 18, 2025

View reviewed changes

packages/nuxt/src/pages/utils.ts Fixed Show fixed Hide fixed

huang-julien marked this pull request as ready for review October 20, 2025 19:13

danielroe reviewed Oct 21, 2025

View reviewed changes

huang-julien and others added 2 commits November 23, 2025 16:14

Merge branch 'main' into feat/33254

58b9438

recfactor: getMetaRouteFromNuxtPage and getRouteFromNuxtPage

e3022f8

github-advanced-security bot found potential problems Nov 23, 2025

View reviewed changes

packages/nuxt/src/pages/utils.ts Fixed Show fixed Hide fixed

packages/nuxt/src/pages/utils.ts Fixed Show fixed Hide fixed

huang-julien marked this pull request as draft November 23, 2025 16:24

[autofix.ci] apply automated fixes

02c6c07

huang-julien marked this pull request as ready for review November 23, 2025 22:24

danielroe added this to the 4.3 milestone Dec 16, 2025

danielroe and others added 2 commits December 16, 2025 14:53

Merge branch 'main' into feat/33254

6e163ef

[autofix.ci] apply automated fixes

32cd0bf

Flo0806 mentioned this pull request Feb 4, 2026

About keepalive list control for pages #34116

Closed

danielroe added 2 commits February 24, 2026 21:39

Merge remote-tracking branch 'origin/main' into feat/33254

6839bd6

# Conflicts: # packages/nuxt/src/pages/utils.ts # packages/nuxt/test/__snapshots__/pages-override-meta-enabled.test.ts.snap # packages/nuxt/test/pages.test.ts # test/bundle.test.ts

refactor: split out helper functions

5c639b1

github-advanced-security bot found potential problems Feb 24, 2026

View reviewed changes

packages/nuxt/src/pages/utils.ts Dismissed Show dismissed Hide dismissed

packages/nuxt/src/pages/utils.ts Fixed Show fixed Hide fixed

autofix-ci bot and others added 2 commits February 24, 2026 21:53

[autofix.ci] apply automated fixes

e1f98b5

fix: don't assign name to server pages

36cd221

github-advanced-security bot found potential problems Feb 24, 2026

View reviewed changes

packages/nuxt/src/pages/utils.ts Fixed Show fixed Hide fixed

packages/nuxt/src/pages/utils.ts Dismissed Show dismissed Hide dismissed

packages/nuxt/src/pages/utils.ts Fixed Show fixed Hide fixed

Merge remote-tracking branch 'origin/main' into feat/33254

70a85d4

danielroe added 4 commits February 25, 2026 11:43

fix: restore logic

86d2422

refactor: simplify logic and reduce diff

387c03c

docs: add docs for normalizePageNames

b062581

feat: default to true when compatibilityVersion: 5

810193e

danielroe approved these changes Feb 25, 2026

View reviewed changes

danielroe changed the title ~~feat(nuxt): experimental page component name normalisation~~ feat(nuxt,schema): experimentally normalise page component names to match route Feb 25, 2026

github-advanced-security bot found potential problems Feb 25, 2026

View reviewed changes

packages/nuxt/src/pages/utils.ts Dismissed Show dismissed Hide dismissed

packages/nuxt/src/pages/utils.ts Dismissed Show dismissed Hide dismissed

danielroe enabled auto-merge February 25, 2026 11:56

coderabbitai bot reviewed Feb 25, 2026

View reviewed changes

docs/1.getting-started/18.upgrade.md Show resolved Hide resolved

docs/3.guide/6.going-further/1.experimental-features.md Outdated Show resolved Hide resolved

Merge remote-tracking branch 'origin/main' into feat/33254

9f3f2a8

# Conflicts: # docs/1.getting-started/18.upgrade.md

coderabbitai bot reviewed Feb 25, 2026

View reviewed changes

docs: apply coderabbit comments

7e5b326

danielroe disabled auto-merge February 25, 2026 16:08

danielroe added this pull request to the merge queue Feb 25, 2026

Merged via the queue into main with commit 9698f38 Feb 25, 2026
57 checks passed

danielroe deleted the feat/33254 branch February 25, 2026 16:27

github-actions bot mentioned this pull request Feb 25, 2026

v4.4.0 #34382

Merged

This was referenced Mar 8, 2026

v5.0.0 #34466

Closed

v5.0.0 #34497

Draft

Uh oh!

Conversation

huang-julien commented Oct 18, 2025

📚 Description

Uh oh!

bolt-new-by-stackblitz bot commented Oct 18, 2025

Uh oh!

Uh oh!

pkg-pr-new bot commented Oct 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codspeed-hq bot commented Oct 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

coderabbitai bot commented Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Uh oh!

danielroe Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

huang-julien Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

danielroe Oct 22, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

danielroe left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

pkg-pr-new bot commented Oct 18, 2025 •

edited

Loading

codspeed-hq bot commented Oct 18, 2025 •

edited

Loading

coderabbitai bot commented Oct 20, 2025 •

edited

Loading