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:
- #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: Delba de Oliveira <[email protected]>

Author: ijjk

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
 

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 |

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 `<Link />` 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 `<Link />` 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.