From 367c6e68eee24b9dcd2a426683604d9b28005699 Mon Sep 17 00:00:00 2001 From: JJ Kasper Date: Tue, 17 Sep 2024 12:46:38 -0700 Subject: [PATCH] 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 `` since it was fairly out of date and lacking any info about app router behavior. --------- Co-authored-by: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com> --- .../04-caching/index.mdx | 8 ++++---- .../05-next-config-js/staleTimes.mdx | 19 ++++++++++++------- packages/next/src/client/link.tsx | 18 +++++++++++++----- 3 files changed, 29 insertions(+), 16 deletions(-) diff --git a/docs/02-app/01-building-your-application/04-caching/index.mdx b/docs/02-app/01-building-your-application/04-caching/index.mdx index ac03be2436fda..5d6c3228c9b8d 100644 --- a/docs/02-app/01-building-your-application/04-caching/index.mdx +++ b/docs/02-app/01-building-your-application/04-caching/index.mdx @@ -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: - **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): - - **Default Prefetching** (`prefetch={null}` or unspecified): 30 seconds - - **Full Prefetching**: (`prefetch={true}` or `router.prefetch`): 5 minutes +- **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): not cached for dynamic pages, 5 minutes for static pages. + - **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. -> **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 diff --git a/docs/02-app/02-api-reference/05-next-config-js/staleTimes.mdx b/docs/02-app/02-api-reference/05-next-config-js/staleTimes.mdx index d3d61b5df4729..0efe7cb11b61f 100644 --- a/docs/02-app/02-api-reference/05-next-config-js/staleTimes.mdx +++ b/docs/02-app/02-api-reference/05-next-config-js/staleTimes.mdx @@ -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 `dynamic` property is used when the `prefetch` prop on `Link` is left unspecified. - - Default: 30 seconds -- 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 `dynamic` property is used when the page is neither statically generated nor fully prefetched (i.e., with prefetch={true}). + - Default: 0 seconds (not cached) +- 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 > **Good to know:** > > - [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 change [back/forward caching](/docs/app/building-your-application/caching#router-cache) behavior to prevent layout shift & 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. +> - 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#client-side-router-cache) behavior to prevent layout shift and to prevent losing the browser scroll position. -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 | diff --git a/packages/next/src/client/link.tsx b/packages/next/src/client/link.tsx index 400c03282f461..af5ca061c6a07 100644 --- a/packages/next/src/client/link.tsx +++ b/packages/next/src/client/link.tsx @@ -57,7 +57,7 @@ type InternalLinkProps = { */ 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` */ @@ -70,12 +70,20 @@ type InternalLinkProps = { passHref?: boolean /** * Prefetch the page in the background. - * Any `` that is in the viewport (initially or through scroll) will be preloaded. - * 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. + * Any `` that is in the viewport (initially or through scroll) will be prefetched. + * 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. * When `false` `href` has to include the locale as the default behavior is disabled.