Unverified Commit ad292fb3 authored by Joseph's avatar Joseph Committed by GitHub

docs: update instant navs guide (#95173)

Narrowing down a few confusion items, and adding screenshots for the nav
inspector.
parent 2da72913
...@@ -37,7 +37,7 @@ export default function Page() { ...@@ -37,7 +37,7 @@ export default function Page() {
### `'allow-runtime'` ### `'allow-runtime'`
Allows Next.js to prefetch this segment at runtime. Today, setting this option causes Next.js to issue a runtime prefetch request, so the server can render a fresh response that includes runtime data like cookies, headers, and search params. Use this for personalized content when the latency and cost of runtime prefetching are appropriate for the segment. Allows Next.js to prefetch this segment at runtime. Setting this option lets the server render a fresh response that resolves per-link runtime data: `params`, `searchParams`, and the full URL. Cookies and headers don't need `'allow-runtime'`. The framework already includes them in the [App Shell](/docs/app/glossary#app-shell) when the route reads them. Use this for personalized content when the latency and cost of runtime prefetching are appropriate for the segment.
> **Good to know**: When Next.js runtime-prefetches a segment, all downstream segments are included in the same runtime prefetch request. Segments deeper in the tree that are configured with `'force-disabled'` will still be prefetched as part of the runtime response. > **Good to know**: When Next.js runtime-prefetches a segment, all downstream segments are included in the same runtime prefetch request. Segments deeper in the tree that are configured with `'force-disabled'` will still be prefetched as part of the runtime response.
...@@ -67,7 +67,7 @@ A prefetch starts with a `<Link>` that expresses intent (should this destination ...@@ -67,7 +67,7 @@ A prefetch starts with a `<Link>` that expresses intent (should this destination
A destination can't know which links target it, so the segment config caps what any `<Link prefetch={true}>` pulls: A destination can't know which links target it, so the segment config caps what any `<Link prefetch={true}>` pulls:
- [`'allow-runtime'`](#allow-runtime): App Shell plus runtime data (cookies, headers, search params). - [`'allow-runtime'`](#allow-runtime): App Shell plus per-link runtime data (`params`, `searchParams`, the full URL).
- [`'partial'`](#partial): App Shell only. - [`'partial'`](#partial): App Shell only.
- [`'force-disabled'`](#force-disabled): skip segment data entirely. - [`'force-disabled'`](#force-disabled): skip segment data entirely.
......
...@@ -52,7 +52,7 @@ The pattern is similar to per-route code splitting in single-page apps: one arti ...@@ -52,7 +52,7 @@ The pattern is similar to per-route code splitting in single-page apps: one arti
> **Good to know**: Routes that read `cookies()` or `headers()` produce an App Shell that includes session data. The framework auto-detects this, and the shell is cached per session on the client, not shared across users. > **Good to know**: Routes that read `cookies()` or `headers()` produce an App Shell that includes session data. The framework auto-detects this, and the shell is cached per session on the client, not shared across users.
A link can ask for more than the App Shell with [`<Link prefetch={true}>`](/docs/app/api-reference/components/link#prefetch). If the destination opts into [`prefetch = 'allow-runtime'`](/docs/app/api-reference/file-conventions/route-segment-config/prefetch#allow-runtime), the prefetch includes runtime data like cookies, headers, and search params. A link can ask for more than the App Shell with [`<Link prefetch={true}>`](/docs/app/api-reference/components/link#prefetch). If the destination opts into [`prefetch = 'allow-runtime'`](/docs/app/api-reference/file-conventions/route-segment-config/prefetch#allow-runtime), the prefetch also resolves per-link runtime data like `params`, `searchParams`, and the full URL.
> **Good to know**: If you use `<Link prefetch={true}>` to a route that hasn't opted into Partial Prefetching, a dev console error suggests enabling `partialPrefetching` app-wide or `prefetch = 'partial'` on the segment. The [dev warning Insight](/docs/messages/instant-link-prefetch-partial) covers each fix in detail. > **Good to know**: If you use `<Link prefetch={true}>` to a route that hasn't opted into Partial Prefetching, a dev console error suggests enabling `partialPrefetching` app-wide or `prefetch = 'partial'` on the segment. The [dev warning Insight](/docs/messages/instant-link-prefetch-partial) covers each fix in detail.
......
...@@ -12,7 +12,7 @@ The Next.js router introduced in version 13, built on top of React Server Compon ...@@ -12,7 +12,7 @@ The Next.js router introduced in version 13, built on top of React Server Compon
## App Shell ## App Shell
A per-route prerender containing only the generic, reusable parts of a page: what Next.js can produce without any URL-specific data. Used as the loading state of last resort by [ISR with Cache Components](/docs/app/guides/incremental-static-regeneration-cache-components) and [runtime prefetching](/docs/app/guides/runtime-prefetching). A per-route prerender containing the parts of a page that don't depend on URL-specific data. Routes that read `cookies()` or `headers()` produce a session-personalized variant, cached per session on the client. Used as the prefetch payload during client navigations, the loading state during [runtime prefetching](/docs/app/guides/runtime-prefetching), and the fallback for [ISR with Cache Components](/docs/app/guides/incremental-static-regeneration-cache-components).
# B # B
...@@ -162,7 +162,7 @@ A pattern that allows simultaneously or conditionally rendering multiple pages w ...@@ -162,7 +162,7 @@ A pattern that allows simultaneously or conditionally rendering multiple pages w
## Partial Prefetching ## Partial Prefetching
A prefetching strategy for [Cache Components](#cache-components) routes where `<Link>` loads only a per-route [App Shell](#app-shell) by default. The page's cached content is downloaded only when the link sets `prefetch={true}`, and dynamic content is never prefetched. Enable with [`partialPrefetching: true`](/docs/app/api-reference/config/next-config-js/partialPrefetching) in `next.config.ts`. Learn more in the [Adopting Partial Prefetching guide](/docs/app/guides/adopting-partial-prefetching). A prefetching strategy for [Cache Components](#cache-components) routes where `<Link>` loads a per-route [App Shell](#app-shell) by default. The page's cached content is downloaded only when the link sets `prefetch={true}`, and uncached reads stay behind their `<Suspense>` boundaries until navigation completes. Enable with [`partialPrefetching: true`](/docs/app/api-reference/config/next-config-js/partialPrefetching) in `next.config.ts`. Learn more in the [Adopting Partial Prefetching guide](/docs/app/guides/adopting-partial-prefetching).
## Partial Prerendering (PPR) ## Partial Prerendering (PPR)
......
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