Unverified Commit d76ff78c authored by Aurora Scharff's avatar Aurora Scharff Committed by GitHub

docs: clarify blocking route response status (#100191)

## What?

- Correct examples that conflated not-found, forbidden, or unauthorized
UI with a guaranteed HTTP status.
- Clarify that `instant = false` does not buffer the HTTP response or
guarantee a later `404`.
- Update the streaming and status-code docs for Cache Components while
keeping the existing `notFound()` example.
- Clarify that HTML-limited bots wait for `generateMetadata`, after
which the page can continue streaming.

## Why?

The existing docs tied status commitment too closely to visible HTML and
Suspense. With Cache Components, an empty prerendered shell can start
the response before request-time rendering resumes. A later
`notFound()`, `forbidden()`, or `unauthorized()` call renders its
fallback UI and adds `noindex`, but it cannot change a committed `200`
status.

Proxy can provide an early request-time status. Redirects configured in
`next.config.js` also run before page rendering and can return an HTTP
redirect response.

Supersedes: #99801

Related implementation PR: #99218

Related Discussion: #100192

## Testing

- Prettier on all changed files
- MDX ESLint on all changed files
- `git diff --check`
parent a7a0dca7
...@@ -414,9 +414,9 @@ export default async function Page({ params }) { ...@@ -414,9 +414,9 @@ export default async function Page({ params }) {
} }
``` ```
With the `loading` boundary removed, no fallback can render while the page awaits `params` and the product lookup. Removing `use cache` means the lookup also runs for each request. The server waits for both before returning the product page or a `404`. During a client navigation, the destination has no fallback to show until this work completes. With the `loading` boundary removed, no fallback can render while the page awaits `params` and the product lookup. Removing `use cache` means the lookup also runs for each request. During a client navigation, the current page stays visible until the product page or not-found UI is ready.
[`instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) disables instant-navigation validation for this route, including the check that its static shell is non-empty. It does not change the rendering model or prevent prerendering. [`instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) disables instant-navigation validation for this route, including the non-empty static shell check. This lets the navigation wait for the product page or not-found UI, while the route can still prerender.
The build output now shows: The build output now shows:
......
...@@ -150,7 +150,7 @@ export const getDictionary = async (locale) => dictionaries[locale]() ...@@ -150,7 +150,7 @@ export const getDictionary = async (locale) => dictionaries[locale]()
Given the currently selected language, we can fetch the dictionary inside of a layout or page. Given the currently selected language, we can fetch the dictionary inside of a layout or page.
Since `lang` is typed as `string`, using `hasLocale` narrows the type to your supported locales. It also ensures a 404 is returned if a translation is missing, rather than a runtime error. Since `lang` is typed as `string`, using `hasLocale` narrows the type to your supported locales. Calling `notFound()` for an unsupported locale renders the not-found UI.
```tsx filename="app/[lang]/page.tsx" switcher ```tsx filename="app/[lang]/page.tsx" switcher
import { notFound } from 'next/navigation' import { notFound } from 'next/navigation'
......
...@@ -614,11 +614,11 @@ Once streaming begins, the HTTP response headers (including the status code) hav ...@@ -614,11 +614,11 @@ Once streaming begins, the HTTP response headers (including the status code) hav
### Status codes ### Status codes
When a `<Suspense>` fallback renders or a component suspends, the server must commit to `200 OK` in order to start sending the HTML stream. If a [`notFound()`](/docs/app/api-reference/functions/not-found) fires mid-stream, Next.js cannot go back and change the status to 404. Instead, it injects `<meta name="robots" content="noindex">` into the streamed HTML so that search engines don't index the page. Similarly, a [`redirect()`](/docs/app/api-reference/functions/redirect) mid-stream becomes a client-side redirect rather than an HTTP redirect header. When a `<Suspense>` fallback renders or a component suspends, the server must commit to `200 OK` to start sending the HTML stream. If a [`notFound()`](/docs/app/api-reference/functions/not-found) fires mid-stream, Next.js cannot go back and change the status to `404`. Instead, it injects `<meta name="robots" content="noindex">` into the streamed HTML so that search engines don't index the page. Similarly, a [`redirect()`](/docs/app/api-reference/functions/redirect) mid-stream becomes a client-side redirect rather than an HTTP redirect header.
### When does streaming start? ### When does streaming start?
The response body begins streaming when a Suspense fallback renders (for example, a `loading.tsx`) or when a component suspends under a `<Suspense>` boundary. To get a real HTTP status code for errors, place `notFound()` **before** any `await` or `<Suspense>` boundary: The response body begins streaming when a Suspense fallback renders (for example, a `loading.tsx`) or when a component suspends under a `<Suspense>` boundary. To return a `404`, place `notFound()` before the boundary:
```tsx filename="app/post/[slug]/page.tsx" switcher ```tsx filename="app/post/[slug]/page.tsx" switcher
import { Suspense } from 'react' import { Suspense } from 'react'
...@@ -637,7 +637,7 @@ export default async function PostPage({ ...@@ -637,7 +637,7 @@ export default async function PostPage({
}) { }) {
const { slug } = await params const { slug } = await params
const exists = await checkSlugExists(slug) // Fast existence check const exists = await checkSlugExists(slug) // Fast existence check
if (!exists) notFound() // Real 404, before any Suspense boundary if (!exists) notFound() // Returns a 404 before streaming starts
return ( return (
<Suspense fallback={<p>Loading post...</p>}> <Suspense fallback={<p>Loading post...</p>}>
...@@ -660,7 +660,7 @@ export async function generateStaticParams() { ...@@ -660,7 +660,7 @@ export async function generateStaticParams() {
export default async function PostPage({ params }) { export default async function PostPage({ params }) {
const { slug } = await params const { slug } = await params
const exists = await checkSlugExists(slug) // Fast existence check const exists = await checkSlugExists(slug) // Fast existence check
if (!exists) notFound() // Real 404, before any Suspense boundary if (!exists) notFound() // Returns a 404 before streaming starts
return ( return (
<Suspense fallback={<p>Loading post...</p>}> <Suspense fallback={<p>Loading post...</p>}>
...@@ -670,7 +670,9 @@ export default async function PostPage({ params }) { ...@@ -670,7 +670,9 @@ export default async function PostPage({ params }) {
} }
``` ```
> **Good to know:** You can also reject requests early using [`proxy`](/docs/app/api-reference/file-conventions/proxy) (for redirects, rewrites, or returning a response) or [`next.config.js` redirects](/docs/app/api-reference/config/next-config-js/redirects). Both run before the page renders, so HTTP status codes are still available. > **Good to know:** With [Cache Components](/docs/app/getting-started/caching), Next.js sends the prerendered shell and headers that preload CSS, fonts, and images while the request-time check runs. This starts a `200` response even when the shell has no visible UI or the route sets `instant = false`. A later `notFound()` still renders the not-found UI and adds `noindex`.
>
> To return a request-time `404`, use [Proxy](/docs/app/api-reference/file-conventions/proxy) before the page renders. Proxy can also redirect, rewrite, or return a response before rendering starts. Redirects configured in [`next.config.js`](/docs/app/api-reference/config/next-config-js/redirects) also run before the page renders.
### Bots and crawlers ### Bots and crawlers
......
...@@ -80,7 +80,9 @@ export const instant = true ...@@ -80,7 +80,9 @@ export const instant = true
Navigations from outside into a tab are allowed to block at the layout. Navigations between tabs are validated for instant UI. Navigations from outside into a tab are allowed to block at the layout. Navigations between tabs are validated for instant UI.
You don't need to add `false` to ancestors of an instant page just because they do something blocking — a higher-up `instant = true` doesn't force its descendants to validate, and leaving an ancestor unconfigured is fine. Reach for `false` only when you've configured a deeper page as instant and need to exempt navigations that pass through a blocking ancestor. You don't need to add `false` to ancestors of an instant page just because they do something blocking. A higher-up `instant = true` doesn't force its descendants to validate, and leaving an ancestor unconfigured is fine. Reach for `false` only when you've configured a deeper page as instant and need to exempt navigations that pass through a blocking ancestor.
`instant = false` controls instant-navigation validation. The route still uses prerendering and streaming. See [Status codes](/docs/app/api-reference/file-conventions/loading#status-codes).
### Disabling static shell validation ### Disabling static shell validation
......
...@@ -104,20 +104,26 @@ Streaming page responses begin with a `200` status code. ...@@ -104,20 +104,26 @@ Streaming page responses begin with a `200` status code.
The initial response headers set the status for the rest of the response. Next.js can then stream redirects and HTTP access fallbacks with [`redirect`](/docs/app/api-reference/functions/redirect), [`notFound`](/docs/app/api-reference/functions/not-found), [`forbidden`](/docs/app/api-reference/functions/forbidden), or [`unauthorized`](/docs/app/api-reference/functions/unauthorized). The initial response headers set the status for the rest of the response. Next.js can then stream redirects and HTTP access fallbacks with [`redirect`](/docs/app/api-reference/functions/redirect), [`notFound`](/docs/app/api-reference/functions/not-found), [`forbidden`](/docs/app/api-reference/functions/forbidden), or [`unauthorized`](/docs/app/api-reference/functions/unauthorized).
> **Good to know:** With Cache Components, Next.js sends the prerendered shell first, along with headers that preload resources such as CSS, fonts, and images. Sending the shell starts the response with a `200`, even when the shell has no visible UI.
For example, when a 404 page is streamed to the client, Next.js includes a `<meta name="robots" content="noindex">` tag in the streamed HTML. This prevents search engines from indexing that URL even if the HTTP status is 200. See Google’s guidance on the [`robots` meta tag](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag). For example, when a 404 page is streamed to the client, Next.js includes a `<meta name="robots" content="noindex">` tag in the streamed HTML. This prevents search engines from indexing that URL even if the HTTP status is 200. See Google’s guidance on the [`robots` meta tag](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag).
For more context, see [Does streaming affect SEO and can streamed content be indexed?](https://vercel.com/kb/guide/does-streaming-affect-seo) and [How Google handles JavaScript throughout the indexing process](https://vercel.com/blog/how-google-handles-javascript-throughout-the-indexing-process).
Some crawlers may label these responses as “soft 404s”. The `noindex` tag keeps them out of search results. Some crawlers may label these responses as “soft 404s”. The `noindex` tag keeps them out of search results.
Run the corresponding check before the response body streams to return a `404`, `403`, or `401` status for compliance or analytics. Run the corresponding check before streaming starts to return a `404`, `403`, or `401` status for compliance or analytics.
For a `404`, you can check the slug in [Proxy](/docs/app/api-reference/file-conventions/proxy), then rewrite it to a not-found route or [return a `404` response](/docs/app/api-reference/file-conventions/proxy#producing-a-response). Keep Proxy checks fast, and avoid fetching full content there. For a `404`, you can check the slug in [Proxy](/docs/app/api-reference/file-conventions/proxy), then rewrite it to a not-found route or [return a `404` response](/docs/app/api-reference/file-conventions/proxy#producing-a-response). Keep Proxy checks fast, and avoid fetching full content there.
<details> <details>
<summary>When is the response body streamed?</summary> <summary>When does streaming start?</summary>
Starting the stream sends the headers and fixes the status code.
The response body starts streaming when a Suspense fallback renders (for example, a `loading.tsx`) or when a Server Component suspends under a `<Suspense>` boundary. Calling `notFound()`, `forbidden()`, or `unauthorized()` before this point preserves its `404`, `403`, or `401` status. Without Cache Components, rendering a fallback from `loading.js` or `<Suspense>` starts streaming. If neither has started the response, Next.js can still return a `404`, `403`, or `401` when the corresponding interrupt runs.
Starting the stream sends the response headers and fixes the status code. With Cache Components, an interrupt can preserve its status when it runs during prerendering, before the response begins. A request-time check inside the page runs after the shell is sent, even when the shell is empty and the route sets `instant = false`, so the status remains `200`.
</details> </details>
......
...@@ -10,7 +10,7 @@ related: ...@@ -10,7 +10,7 @@ related:
- app/api-reference/config/next-config-js/authInterrupts - app/api-reference/config/next-config-js/authInterrupts
--- ---
The `forbidden` function throws an error that renders a Next.js 403 page. It's useful for handling authorization errors in your application. You can customize the UI using the [`forbidden.js` file](/docs/app/api-reference/file-conventions/forbidden). The `forbidden` function throws an error that renders the forbidden UI. It's useful for handling authorization errors in your application. You can customize the UI using the [`forbidden.js` file](/docs/app/api-reference/file-conventions/forbidden).
Invoking `forbidden()` throws a `NEXT_HTTP_ERROR_FALLBACK;403` error and terminates rendering of the route segment where it was thrown. Next.js also injects a `<meta name="robots" content="noindex" />` tag so the page is not indexed. Because it works by throwing, call it in the render path: a component, or a function a component `await`s. A call left in an un-awaited promise throws where nothing catches it, and no forbidden UI renders. Invoking `forbidden()` throws a `NEXT_HTTP_ERROR_FALLBACK;403` error and terminates rendering of the route segment where it was thrown. Next.js also injects a `<meta name="robots" content="noindex" />` tag so the page is not indexed. Because it works by throwing, call it in the render path: a component, or a function a component `await`s. A call left in an un-awaited promise throws where nothing catches it, and no forbidden UI renders.
...@@ -184,7 +184,7 @@ export default function Forbidden() { ...@@ -184,7 +184,7 @@ export default function Forbidden() {
The response starts streaming from the `<Suspense>` boundary before `forbidden()` runs, so it keeps its `200` status. Next.js adds a `noindex` tag. The response starts streaming from the `<Suspense>` boundary before `forbidden()` runs, so it keeps its `200` status. Next.js adds a `noindex` tag.
Calling `forbidden()` before streaming starts returns a `403`. A page that reaches `forbidden()` during prerendering can remain `○` Static and serve a `403`. A request-time check can run in [Proxy](/docs/app/api-reference/file-conventions/proxy) before the page renders. See [Status codes](/docs/app/api-reference/file-conventions/loading#status-codes). `forbidden()` returns a `403` when it runs before the response starts, including during prerendering. See [Status codes](/docs/app/api-reference/file-conventions/loading#status-codes).
### Role-based route protection ### Role-based route protection
......
...@@ -1243,7 +1243,7 @@ Streaming metadata allows Next.js to render and send the initial UI to the brows ...@@ -1243,7 +1243,7 @@ Streaming metadata allows Next.js to render and send the initial UI to the brows
When `generateMetadata` resolves, the resulting metadata tags are appended to the `<body>` tag. We have verified that metadata is interpreted correctly by bots that execute JavaScript and inspect the full DOM (e.g. `Googlebot`). When `generateMetadata` resolves, the resulting metadata tags are appended to the `<body>` tag. We have verified that metadata is interpreted correctly by bots that execute JavaScript and inspect the full DOM (e.g. `Googlebot`).
For **HTML-limited bots** that can’t execute JavaScript (e.g. `facebookexternalhit`), metadata continues to block page rendering. The resulting metadata will be available in the `<head>` tag. For **HTML-limited bots** that can’t execute JavaScript (e.g. `facebookexternalhit`), Next.js waits for `generateMetadata` before starting the response. The resulting metadata is available in the `<head>` tag. After `generateMetadata` resolves, Next.js can start the response and stream the remaining page content.
Next.js automatically detects **HTML-limited bots** by looking at the User Agent header. You can use the [`htmlLimitedBots`](/docs/app/api-reference/config/next-config-js/htmlLimitedBots) option in your Next.js config file to override the default [User Agent list](https://github.com/vercel/next.js/blob/canary/packages/next/src/shared/lib/router/utils/html-bots.ts). Next.js automatically detects **HTML-limited bots** by looking at the User Agent header. You can use the [`htmlLimitedBots`](/docs/app/api-reference/config/next-config-js/htmlLimitedBots) option in your Next.js config file to override the default [User Agent list](https://github.com/vercel/next.js/blob/canary/packages/next/src/shared/lib/router/utils/html-bots.ts).
......
...@@ -8,7 +8,7 @@ related: ...@@ -8,7 +8,7 @@ related:
- app/api-reference/functions/unauthorized - app/api-reference/functions/unauthorized
--- ---
The `notFound` function throws an error that renders a Next.js 404 page. It's useful for handling missing resources in your application. You can customize the UI using the [`not-found.js` file](/docs/app/api-reference/file-conventions/not-found). The `notFound` function throws an error that renders the not-found UI. It's useful for handling missing resources in your application. You can customize the UI using the [`not-found.js` file](/docs/app/api-reference/file-conventions/not-found).
Invoking `notFound()` throws a `NEXT_HTTP_ERROR_FALLBACK;404` error and terminates rendering of the route segment where it was thrown. Next.js also injects a `<meta name="robots" content="noindex" />` tag so the page is not indexed. Because it works by throwing, call it in the render path: a component, or a function a component `await`s. A call left in an un-awaited promise throws where nothing catches it, and no not-found UI renders (in development the server logs `⨯ unhandledRejection: NEXT_HTTP_ERROR_FALLBACK;404`). Invoking `notFound()` throws a `NEXT_HTTP_ERROR_FALLBACK;404` error and terminates rendering of the route segment where it was thrown. Next.js also injects a `<meta name="robots" content="noindex" />` tag so the page is not indexed. Because it works by throwing, call it in the render path: a component, or a function a component `await`s. A call left in an un-awaited promise throws where nothing catches it, and no not-found UI renders (in development the server logs `⨯ unhandledRejection: NEXT_HTTP_ERROR_FALLBACK;404`).
...@@ -192,7 +192,7 @@ export default function NotFound() { ...@@ -192,7 +192,7 @@ export default function NotFound() {
The response starts streaming from the `<Suspense>` boundary before `notFound()` runs, so it keeps its `200` status. Next.js adds a `noindex` tag. The response starts streaming from the `<Suspense>` boundary before `notFound()` runs, so it keeps its `200` status. Next.js adds a `noindex` tag.
Calling `notFound()` before streaming starts returns a `404`. A page that reaches `notFound()` during prerendering can remain `○` Static and serve a `404`. A request-time check can run in [Proxy](/docs/app/api-reference/file-conventions/proxy) before the page renders. See [Status codes](/docs/app/api-reference/file-conventions/loading#status-codes). `notFound()` returns a `404` when it runs before the response starts, including during prerendering. See [Status codes](/docs/app/api-reference/file-conventions/loading#status-codes).
### Serving a 404 from a Route Handler ### Serving a 404 from a Route Handler
......
...@@ -10,7 +10,7 @@ related: ...@@ -10,7 +10,7 @@ related:
- app/api-reference/config/next-config-js/authInterrupts - app/api-reference/config/next-config-js/authInterrupts
--- ---
The `unauthorized` function throws an error that renders a Next.js 401 page. It's useful for handling authentication errors, when a request is not signed in. You can customize the UI using the [`unauthorized.js` file](/docs/app/api-reference/file-conventions/unauthorized). The `unauthorized` function throws an error that renders the unauthorized UI. It's useful for handling authentication errors when a request is not signed in. You can customize the UI using the [`unauthorized.js` file](/docs/app/api-reference/file-conventions/unauthorized).
Invoking `unauthorized()` throws a `NEXT_HTTP_ERROR_FALLBACK;401` error and terminates rendering of the route segment where it was thrown. Next.js also injects a `<meta name="robots" content="noindex" />` tag so the page is not indexed. Because it works by throwing, call it in the render path: a component, or a function a component `await`s. A call left in an un-awaited promise throws where nothing catches it, and no unauthorized UI renders. Invoking `unauthorized()` throws a `NEXT_HTTP_ERROR_FALLBACK;401` error and terminates rendering of the route segment where it was thrown. Next.js also injects a `<meta name="robots" content="noindex" />` tag so the page is not indexed. Because it works by throwing, call it in the render path: a component, or a function a component `await`s. A call left in an un-awaited promise throws where nothing catches it, and no unauthorized UI renders.
...@@ -188,7 +188,7 @@ export default function Unauthorized() { ...@@ -188,7 +188,7 @@ export default function Unauthorized() {
The response starts streaming from the `<Suspense>` boundary before `unauthorized()` runs, so it keeps its `200` status. Next.js adds a `noindex` tag. The response starts streaming from the `<Suspense>` boundary before `unauthorized()` runs, so it keeps its `200` status. Next.js adds a `noindex` tag.
Calling `unauthorized()` before streaming starts returns a `401`. A page that reaches `unauthorized()` during prerendering can remain `○` Static and serve a `401`. A request-time check can run in [Proxy](/docs/app/api-reference/file-conventions/proxy) before the page renders. See [Status codes](/docs/app/api-reference/file-conventions/loading#status-codes). `unauthorized()` returns a `401` when it runs before the response starts, including during prerendering. See [Status codes](/docs/app/api-reference/file-conventions/loading#status-codes).
### Displaying login UI to unauthenticated users ### Displaying login UI to unauthenticated users
...@@ -266,7 +266,7 @@ import db from '@/app/lib/db' ...@@ -266,7 +266,7 @@ import db from '@/app/lib/db'
export async function updateProfile(data: FormData) { export async function updateProfile(data: FormData) {
const session = await verifySession() const session = await verifySession()
// If the user is not authenticated, return a 401 // If unauthenticated, render the nearest unauthorized boundary
if (!session) { if (!session) {
unauthorized() unauthorized()
} }
...@@ -286,7 +286,7 @@ import db from '@/app/lib/db' ...@@ -286,7 +286,7 @@ import db from '@/app/lib/db'
export async function updateProfile(data) { export async function updateProfile(data) {
const session = await verifySession() const session = await verifySession()
// If the user is not authenticated, return a 401 // If unauthenticated, render the nearest unauthorized boundary
if (!session) { if (!session) {
unauthorized() unauthorized()
} }
...@@ -309,7 +309,7 @@ export async function GET(req: NextRequest): Promise<NextResponse> { ...@@ -309,7 +309,7 @@ export async function GET(req: NextRequest): Promise<NextResponse> {
// Verify the user's session // Verify the user's session
const session = await verifySession() const session = await verifySession()
// If no session exists, return a 401 and render unauthorized.tsx // If no session exists, return an empty 401 response
if (!session) { if (!session) {
unauthorized() unauthorized()
} }
...@@ -326,7 +326,7 @@ import { unauthorized } from 'next/navigation' ...@@ -326,7 +326,7 @@ import { unauthorized } from 'next/navigation'
export async function GET() { export async function GET() {
const session = await verifySession() const session = await verifySession()
// If the user is not authenticated, return a 401 and render unauthorized.tsx // If the user is not authenticated, return an empty 401 response
if (!session) { if (!session) {
unauthorized() unauthorized()
} }
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment