Commit 367c6e68 authored by JJ Kasper's avatar JJ Kasper

update prefetching jsdoc & documentation (#68047)

Clarifies that static vs dynamic resources now influence the static /
dynamic staleTime that is used which should hopefully be more intuitive.

Reference PR:
- https://github.com/vercel/next.js/pull/67868

Also updates the JSDoc for `<Link />` since it was fairly out of date
and lacking any info about app router behavior.

---------
Co-authored-by: 's avatarDelba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
parent 16ad3683
...@@ -363,13 +363,13 @@ This results in an improved navigation experience for the user: ...@@ -363,13 +363,13 @@ This results in an improved navigation experience for the user:
The cache is stored in the browser's temporary memory. Two factors determine how long the router cache lasts: The cache is stored in the browser's temporary memory. Two factors determine how long the router cache lasts:
- **Session**: The cache persists across navigation. However, it's cleared on page refresh. - **Session**: The cache persists across navigation. However, it's cleared on page refresh.
- **Automatic Invalidation Period**: The cache of an individual segment is automatically invalidated after a specific time. The duration depends on how the resource was [prefetched](/docs/app/api-reference/components/link#prefetch): - **Automatic Invalidation Period**: The cache of layouts and loading states is automatically invalidated after a specific time. The duration depends on how the resource was [prefetched](/docs/app/api-reference/components/link#prefetch), and if the resource was [statically generated](/docs/app/building-your-application/rendering/server-components#static-rendering-default):
- **Default Prefetching** (`prefetch={null}` or unspecified): 30 seconds - **Default Prefetching** (`prefetch={null}` or unspecified): not cached for dynamic pages, 5 minutes for static pages.
- **Full Prefetching**: (`prefetch={true}` or `router.prefetch`): 5 minutes - **Full Prefetching** (`prefetch={true}` or `router.prefetch`): 5 minutes for both static & dynamic pages.
While a page refresh will clear **all** cached segments, the automatic invalidation period only affects the individual segment from the time it was prefetched. While a page refresh will clear **all** cached segments, the automatic invalidation period only affects the individual segment from the time it was prefetched.
> **Note**: There is [experimental support](/docs/app/api-reference/next-config-js/staleTimes) for configuring these values as of v14.2.0-canary.53. > **Good to know**: The experimental [`staleTimes`](/docs/app/api-reference/next-config-js/staleTimes) config option can be used to adjust the automatic invalidation times mentioned above.
### Invalidation ### Invalidation
......
...@@ -27,16 +27,21 @@ module.exports = nextConfig ...@@ -27,16 +27,21 @@ module.exports = nextConfig
The `static` and `dynamic` properties correspond with the time period (in seconds) based on different types of [link prefetching](/docs/app/api-reference/components/link#prefetch). The `static` and `dynamic` properties correspond with the time period (in seconds) based on different types of [link prefetching](/docs/app/api-reference/components/link#prefetch).
- The `dynamic` property is used when the `prefetch` prop on `Link` is left unspecified. - The `dynamic` property is used when the page is neither statically generated nor fully prefetched (i.e., with prefetch={true}).
- Default: 30 seconds - Default: 0 seconds (not cached)
- The `static` property is used when the `prefetch` prop on `Link` is set to `true`, or when calling [`router.prefetch`](/docs/app/building-your-application/caching#routerprefetch). - The `static` property is used for statically generated pages, or when the `prefetch` prop on `Link` is set to `true`, or when calling [`router.prefetch`](/docs/app/building-your-application/caching#routerprefetch).
- Default: 5 minutes - Default: 5 minutes
> **Good to know:** > **Good to know:**
> >
> - [Loading boundaries](/docs/app/api-reference/file-conventions/loading) are considered reusable for the `static` period defined in this configuration. > - [Loading boundaries](/docs/app/api-reference/file-conventions/loading) are considered reusable for the `static` period defined in this configuration.
> - This doesn't disable [partial rendering support](/docs/app/building-your-application/routing/linking-and-navigating#4-partial-rendering), **meaning shared layouts won't automatically be refetched every navigation, only the new segment data.** > - This doesn't affect [partial rendering](/docs/app/building-your-application/routing/linking-and-navigating#4-partial-rendering), **meaning shared layouts won't automatically be refetched on every navigation, only the page segment that changes.**
> - This doesn't change [back/forward caching](/docs/app/building-your-application/caching#router-cache) behavior to prevent layout shift & to prevent losing the browser scroll position. > - This doesn't change [back/forward caching](/docs/app/building-your-application/caching#client-side-router-cache) behavior to prevent layout shift and to prevent losing the browser scroll position.
> - The different properties of this config refer to variable levels of "liveness" and are unrelated to whether the segment itself is opting into static or dynamic rendering. In other words, the current `static` default of 5 minutes suggests that data feels static by virtue of it being revalidated infrequently.
You can learn more about the Client Router Cache [here](/docs/app/building-your-application/caching#router-cache). You can learn more about the Client Router Cache [here](/docs/app/building-your-application/caching#client-side-router-cache).
### Version History
| Version | Changes |
| --------- | ------------------------------------ |
| `v14.2.0` | experimental `staleTimes` introduced |
...@@ -57,7 +57,7 @@ type InternalLinkProps = { ...@@ -57,7 +57,7 @@ type InternalLinkProps = {
*/ */
scroll?: boolean scroll?: boolean
/** /**
* Update the path of the current page without rerunning [`getStaticProps`](/docs/pages/building-your-application/data-fetching/get-static-props), [`getServerSideProps`](/docs/pages/building-your-application/data-fetching/get-server-side-props) or [`getInitialProps`](/docs/pages/api-reference/functions/get-initial-props). * Update the path of the current page without rerunning [`getStaticProps`](https://nextjs.org/docs/pages/building-your-application/data-fetching/get-static-props), [`getServerSideProps`](https://nextjs.org/docs/pages/building-your-application/data-fetching/get-server-side-props) or [`getInitialProps`](/docs/pages/api-reference/functions/get-initial-props).
* *
* @defaultValue `false` * @defaultValue `false`
*/ */
...@@ -70,12 +70,20 @@ type InternalLinkProps = { ...@@ -70,12 +70,20 @@ type InternalLinkProps = {
passHref?: boolean passHref?: boolean
/** /**
* Prefetch the page in the background. * Prefetch the page in the background.
* Any `<Link />` that is in the viewport (initially or through scroll) will be preloaded. * Any `<Link />` that is in the viewport (initially or through scroll) will be prefetched.
* Prefetch can be disabled by passing `prefetch={false}`. When `prefetch` is set to `false`, prefetching will still occur on hover in pages router but not in app router. Pages using [Static Generation](/docs/basic-features/data-fetching/get-static-props.md) will preload `JSON` files with the data for faster page transitions. Prefetching is only enabled in production. * Prefetch can be disabled by passing `prefetch={false}`. Prefetching is only enabled in production.
* *
* @defaultValue `true` * In App Router:
* - `null` (default): For statically generated pages, this will prefetch the full React Server Component data. For dynamic pages, this will prefetch up to the nearest route segment with a [`loading.js`](https://nextjs.org/docs/app/api-reference/file-conventions/loading) file. If there is no loading file, it will not fetch the full tree to avoid fetching too much data.
* - `true`: This will prefetch the full React Server Component data for all route segments, regardless of whether they contain a segment with `loading.js`.
* - `false`: This will not prefetch any data, even on hover.
*
* In Pages Router:
* - `true` (default): The full route & its data will be prefetched.
* - `false`: Prefetching will not happen when entering the viewport, but will still happen on hover.
* @defaultValue `true` (pages router) or `null` (app router)
*/ */
prefetch?: boolean prefetch?: boolean | null
/** /**
* The active locale is automatically prepended. `locale` allows for providing a different locale. * The active locale is automatically prepended. `locale` allows for providing a different locale.
* When `false` `href` has to include the locale as the default behavior is disabled. * When `false` `href` has to include the locale as the default behavior is disabled.
......
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