docs: update v4 docs with new folder structure #32348

danielroe · 2025-06-09T10:53:52Z

🔗 Linked issue

resolves #32344
resolves #32345

📚 Description

this is a set of changes to update the docs to assume the new v4 folder structure - it will not be backported to the 3.x branch

…ons.ts`

bolt-new-by-stackblitz · 2025-06-09T10:53:54Z

Run & review this pull request in StackBlitz Codeflow.

pkg-pr-new · 2025-06-09T11:01:57Z

Open in StackBlitz

@nuxt/kit

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

nuxt

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

@nuxt/rspack-builder

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

@nuxt/schema

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

@nuxt/vite-builder

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

@nuxt/webpack-builder

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

commit: e8b8af0

codspeed-hq · 2025-06-09T11:12:40Z

CodSpeed Performance Report

Merging #32348 will not alter performance

_{Comparing docs/v4-structure (e8b8af0) with main (cf9f91e)}

Summary

✅ 10 untouched benchmarks

Copilot

Pull Request Overview

This PR updates the documentation to reflect the new Nuxt 4 folder structure. It revises file paths and examples across multiple docs files to remove the "app/" prefix from router options and SPA loading template references, and clarifies the alias mapping in the upgrade guide.

Removed "app/" prefixes from router.options.ts paths and updated related examples
Updated SPA loading template paths from "~~/app/spa-loading-template.html" to "~~/spa-loading-template.html"
Revised directory structure examples and upgrade instructions to match the new folder layout

Reviewed Changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
docs/7.migration/7.component-options.md	Updated scrollToTop instructions to point to the new router.options.ts path
docs/3.api/6.nuxt-config.md	Refined default paths and examples to reflect the new folder structure
docs/3.api/3.utils/define-page-meta.md	Adjusted the router.options.ts reference in the guidance
docs/2.guide/4.recipes/1.custom-routing.md	Replaced "app/router.options.ts" with "router.options.ts" throughout
docs/2.guide/3.going-further/1.experimental-features.md	Updated the SPA loading template path to the new structure
docs/2.guide/2.directory-structure/1.app/1.pages.md	Modified navigation note to reference the updated router.options.ts path
docs/2.guide/2.directory-structure/1.app/.navigation.yml	New navigation file reflecting the directory section changes
docs/2.guide/1.concepts/3.rendering.md	Revised SPA loading template note to indicate the new file path
docs/1.getting-started/18.upgrade.md	Clarified alias mapping and file structure changes in the upgrade instructions
docs/1.getting-started/10.data-fetching.md	Changed a conditional check from "data == null" to "data == undefined" in a Vue template

Comments suppressed due to low confidence (1)

docs/1.getting-started/10.data-fetching.md:44

Consider retaining the check using 'data == null' since it handles both null and undefined values. If the change to 'undefined' is intentional, please confirm that it aligns with the desired logic.

  <div v-if="data == undefined">

coderabbitai · 2025-06-10T09:25:01Z

Walkthrough

The changes primarily update documentation across several files to reflect adjustments in file paths, naming conventions, and default directory structures for Nuxt 4. References to the SPA loading template file path have been corrected from app/spa-loading-template.html to ~/spa-loading-template.html. Mentions of the router options file have been unified from app/router.options.ts to router.options.ts. The documentation now clarifies that the ~ alias points to the app/ directory by default, and example folder structures have been updated accordingly. Additionally, a new navigation YAML file was added, and a conditional check in a Vue template example was modified. No changes were made to exported or public entities.

✨ Finishing Touches

📝 Generate Docstrings

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

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Explain this complex logic.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
- @coderabbitai explain this code block.
- @coderabbitai modularize this function.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read src/utils.ts and explain its main purpose.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
- @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

@coderabbitai pause to pause the reviews on a PR.
@coderabbitai resume to resume the paused reviews.
@coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
@coderabbitai full review to do a full review from scratch and review all the files again.
@coderabbitai summary to regenerate the summary of the PR.
@coderabbitai generate docstrings to generate docstrings for this PR.
@coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
@coderabbitai resolve resolve all the CodeRabbit review comments.
@coderabbitai configuration to show the current CodeRabbit configuration for the repository.
@coderabbitai help to get help.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (4)

docs/1.getting-started/10.data-fetching.md (1)
44-44: Prefer strict undefined check
Using === undefined is clearer and avoids unintended type coercion.

Consider updating as follows:
- <div v-if="data == undefined">
+ <div v-if="data === undefined">
docs/3.api/6.nuxt-config.md (3)
1905-1905: Grammar: include definite article
Missing "the" before "file" in the bullet.
- - If it is unset, it will use `~/spa-loading-template.html` file in one of your layers, if it exists.
+ - If it is unset, it will use the `~/spa-loading-template.html` file in one of your layers, if it exists.
🧰 Tools

🪛 LanguageTool

[uncategorized] ~1905-1905: You might be missing the article “the” here.
Context: ... false. - If it is unset, it will use /spa-loading-template.html` file in one...

(AI_EN_LECTOR_MISSING_DETERMINER_THE)

1911-1911: Wrap example path in code ticks
Enhance readability by formatting the path as inline code.
- **Example**: ~/spa-loading-template.html
+ **Example**: `~/spa-loading-template.html`
1967-1967: Consistent srcDir example
Remove trailing slash to align with default value.
-   srcDir: 'app/'
+   srcDir: 'app'

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between cf9f91e and e8b8af0.

📒 Files selected for processing (12)

docs/1.getting-started/10.data-fetching.md (1 hunks)
docs/1.getting-started/18.upgrade.md (3 hunks)
docs/2.guide/1.concepts/3.rendering.md (1 hunks)
docs/2.guide/2.directory-structure/1.app/.navigation.yml (1 hunks)
docs/2.guide/2.directory-structure/1.app/1.pages.md (1 hunks)
docs/2.guide/3.going-further/1.experimental-features.md (1 hunks)
docs/2.guide/4.recipes/1.custom-routing.md (4 hunks)
docs/3.api/3.utils/define-page-meta.md (1 hunks)
docs/3.api/6.nuxt-config.md (3 hunks)
docs/7.migration/7.component-options.md (1 hunks)
packages/schema/src/config/app.ts (1 hunks)
packages/schema/src/types/schema.ts (2 hunks)

🧰 Additional context used

🪛 LanguageTool

docs/2.guide/1.concepts/3.rendering.md

[uncategorized] ~91-~91: Loose punctuation mark.
Context: ...be rendered until your app is hydrated. :read-more{title="SPA Loading Template" t...

(UNLIKELY_OPENING_PUNCTUATION)

docs/2.guide/2.directory-structure/1.app/1.pages.md

[uncategorized] ~9-~9: Loose punctuation mark.
Context: ...custom-routing#using-approuteroptions). :: ## Usage Pages are Vue components an...

(UNLIKELY_OPENING_PUNCTUATION)

docs/3.api/6.nuxt-config.md

[uncategorized] ~1796-~1796: Loose punctuation mark.
Context: ...ou can use an router.options.ts file. :: See: [Vue Router documentation](h...

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~1905-1905: You might be missing the article “the” here.
Context: ... false. - If it is unset, it will use /spa-loading-template.html` file in one...

(AI_EN_LECTOR_MISSING_DETERMINER_THE)

⏰ Context from checks skipped due to timeout of 90000ms (10)

GitHub Check: test-fixtures (windows-latest, built, webpack, default, manifest-on, json, 20)
GitHub Check: test-fixtures (windows-latest, built, webpack, default, manifest-on, json, 20)
GitHub Check: test-fixtures (windows-latest, built, webpack, default, manifest-on, json, 20)
GitHub Check: test-fixtures (windows-latest, built, webpack, default, manifest-on, json, 20)
GitHub Check: test-fixtures (windows-latest, built, webpack, default, manifest-on, json, 20)
GitHub Check: test-fixtures (windows-latest, built, webpack, default, manifest-on, json, 20)
GitHub Check: test-fixtures (windows-latest, built, webpack, default, manifest-on, json, 20)
GitHub Check: test-fixtures (windows-latest, built, webpack, default, manifest-on, json, 20)
GitHub Check: test-fixtures (windows-latest, built, webpack, default, manifest-on, json, 20)
GitHub Check: test-fixtures (windows-latest, built, webpack, default, manifest-on, json, 20)

🔇 Additional comments (17)

docs/2.guide/1.concepts/3.rendering.md (1)

91-91: Path correction for SPA loading template
The update from ~/app/spa-loading-template.html to ~/spa-loading-template.html correctly reflects the new default alias.

🧰 Tools

🪛 LanguageTool

[uncategorized] ~91-~91: Loose punctuation mark.
Context: ...be rendered until your app is hydrated. :read-more{title="SPA Loading Template" t...

(UNLIKELY_OPENING_PUNCTUATION)

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

457-457: Update SPA loading template reference
Correctly points to ~/spa-loading-template.html instead of the obsolete path under app/.

docs/3.api/3.utils/define-page-meta.md (1)

139-139: Unify router options path reference
The path correctly reflects the new structure (~/router.options.ts).

docs/7.migration/7.component-options.md (1)

106-106: Corrected scroll behaviour override path
The updated path ~/router.options.ts aligns with the revised directory conventions.

docs/2.guide/2.directory-structure/1.app/1.pages.md (1)

9-9: Consistent router options reference

The link has been correctly updated to point at router.options.ts (dropping the app/ prefix) in the custom‐routing guide, reflecting the new folder structure.

🧰 Tools

🪛 LanguageTool

[uncategorized] ~9-~9: Loose punctuation mark.
Context: ...custom-routing#using-approuteroptions). :: ## Usage Pages are Vue components an...

(UNLIKELY_OPENING_PUNCTUATION)

docs/2.guide/2.directory-structure/1.app/.navigation.yml (1)

1-5: New navigation metadata

The added YAML defines the navigation for the "app" section—setting title, titleTemplate, head.title, defaultOpen and icon—aligning with the updated directory overview.

docs/2.guide/4.recipes/1.custom-routing.md (3)

16-29: Unify router config filename

The code block has been updated to use router.options.ts rather than app/router.options.ts, matching the revised default app/ directory alias.

112-114: Update resolver path

Adjusted the resolver invocation to ./runtime/router-options to correspond with the renamed router options file.

173-181: Consistent router options example

The second example likewise now references router.options.ts for the custom history configuration, ensuring uniform names across all examples.

packages/schema/src/config/app.ts (1)

301-307: Correct SPA loading template path

Documentation comments now refer to ~/spa-loading-template.html (without the app/ prefix), in line with the new default srcDir mapping.

packages/schema/src/types/schema.ts (2)

302-308: Align SPA loading template example

The spaLoadingTemplate comment has been updated to use ~/spa-loading-template.html directly, removing any outdated app/ nesting in the example.

595-607: Update srcDir example and structure

Revised the srcDir default to 'app/' and flattened the directory tree to reflect the new standard layout under app/.

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

191-193: Verified updated alias note
Clarifies that ~ now points to app/ by default, in line with the new srcDir.

225-225: Corrected comment for forcing v3 folder structure
The directive now accurately references router.options.ts and spa-loading-template.html without redundant app/ prefix.

437-437: Updated SPA loading template path
Adjusts old ~/app/spa-loading-template.html reference to the new ~/spa-loading-template.html, matching Nuxt 4 behaviour.

docs/3.api/6.nuxt-config.md (2)

1796-1796: Confirmed router options file reference
The note now correctly points users to a standalone router.options.ts file for advanced configuration.

🧰 Tools

🪛 LanguageTool

[uncategorized] ~1796-~1796: Loose punctuation mark.
Context: ...ou can use an router.options.ts file. :: See: [Vue Router documentation](h...

(UNLIKELY_OPENING_PUNCTUATION)

1962-1962: Verified default srcDir description
Defaults correctly state "app" for Nuxt 4 and "." for Nuxt 3 compatibility.

danielroe added 2 commits June 9, 2025 11:52

docs: update some folder structure examples

2525762

docs: update mentions of spa-loading-template.html and `router.opti…

84f28f8

…ons.ts`

github-actions bot added 3.x documentation labels Jun 9, 2025

refactor: update directory structure

e8b8af0

danielroe mentioned this pull request Jun 10, 2025

fix: add redirects for new directory structure nuxt/nuxt.com#1927

Merged

6 tasks

danielroe marked this pull request as ready for review June 10, 2025 09:19

Copilot AI review requested due to automatic review settings June 10, 2025 09:19

Copilot AI reviewed Jun 10, 2025

View reviewed changes

danielroe merged commit c246d9b into main Jun 10, 2025
120 of 124 checks passed

danielroe deleted the docs/v4-structure branch June 10, 2025 09:23

github-actions bot mentioned this pull request Jun 10, 2025

v4.0.0 #27716

Draft

coderabbitai bot reviewed Jun 10, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

docs: update v4 docs with new folder structure #32348

docs: update v4 docs with new folder structure #32348

Uh oh!

danielroe commented Jun 9, 2025

Uh oh!

bolt-new-by-stackblitz bot commented Jun 9, 2025

Uh oh!

pkg-pr-new bot commented Jun 9, 2025 •

edited

Loading

Uh oh!

codspeed-hq bot commented Jun 9, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

coderabbitai bot commented Jun 10, 2025

Chat

Support

CodeRabbit Commands (Invoked using PR comments)

Other keywords and placeholders

CodeRabbit Configuration File (`.coderabbit.yaml`)

Documentation and Community

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Uh oh!

docs: update v4 docs with new folder structure #32348

docs: update v4 docs with new folder structure #32348

Uh oh!

Conversation

danielroe commented Jun 9, 2025

🔗 Linked issue

📚 Description

Uh oh!

bolt-new-by-stackblitz bot commented Jun 9, 2025

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

CodSpeed Performance Report

Merging #32348 will not alter performance

Summary

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

coderabbitai bot commented Jun 10, 2025

Walkthrough

Chat

Support

CodeRabbit Commands (Invoked using PR comments)

Other keywords and placeholders

CodeRabbit Configuration File (.coderabbit.yaml)

Documentation and Community

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

pkg-pr-new bot commented Jun 9, 2025 •

edited

Loading

codspeed-hq bot commented Jun 9, 2025 •

edited

Loading

CodeRabbit Configuration File (`.coderabbit.yaml`)