docs: clarify not-found with dynamic root layouts - #96978
Draft
DavidIlie wants to merge 1 commit into
Draft
Conversation
Contributor
Tests PassedCommit: cd277ca |
Contributor
Stats skippedCommit: cd277ca |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What?
Clarifies how not-found UI works when the only application root layout is nested under a dynamic segment such as
app/[lang]/layout.js.The reference now compares two supported patterns:
global-not-found.jshandles routing-level misses with a hard404, but owns the full document and does not inherit the dynamic layout.app/[lang]/not-found.jsplus[...rest]page preserves the localized layout and follows the normal streamednotFound()status behavior.The localized recipe explicitly tells readers to remove the root
app/not-found.jsboundary before moving it below[lang].Why?
A globally unmatched URL has no resolved value for a dynamic root parameter, so Next.js cannot compose that response with
app/[lang]/layout.js. The existing docs mentionglobal-not-found.jsfor this topology but do not show the stable catch-all alternative or explain its layout and HTTP-status trade-offs.This is intentionally docs-only. The minimal topology builds successfully on current
canarywith both webpack and Turbopack, including Cache Components, so there is no reproducible loader failure to patch.Related to #59180 and discussion #50034.
How?
Adds a focused comparison table, TypeScript and JavaScript catch-all examples, and a link to the streamed status-code guidance.
Verification
pnpm --filter=next buildnpx eslint --config eslint.config.mjs docs/01-app/03-api-reference/03-file-conventions/not-found.mdxcacheComponents: true