From 1fae083c633c909fddd05101f843769cda4b7f03 Mon Sep 17 00:00:00 2001
From: Zack Tanner <zacktanner@gmail.com>
Date: Wed, 3 Apr 2024 11:10:40 -0700
Subject: [PATCH] docs: add experimental staleTimes resource

---
 .../04-caching/index.mdx                      |  2 +
 .../05-next-config-js/staleTimes.mdx          | 41 +++++++++++++++++++
 2 files changed, 43 insertions(+)
 create mode 100644 docs/02-app/02-api-reference/05-next-config-js/staleTimes.mdx

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 5494a3d391082..7f7d66e669bfa 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
@@ -369,6 +369,8 @@ The cache is stored in the browser's temporary memory. Two factors determine how
 
 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.
+
 ### Invalidation
 
 There are two ways you can invalidate the Router Cache:
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
new file mode 100644
index 0000000000000..0bffa0ae1d4d6
--- /dev/null
+++ b/docs/02-app/02-api-reference/05-next-config-js/staleTimes.mdx
@@ -0,0 +1,41 @@
+---
+title: StaleTimes (experimental)
+description: Learn how to override the invalidation time of the Client Router Cache.
+---
+
+> **Warning**: The `staleTimes` configuration is an experimental feature. This configuration strategy will likely change in the future.
+
+`staleTimes` is an experimental feature that allows configuring the [invalidation period](/docs/app/building-your-application/caching#duration-3) of the client router cache.
+
+This configuration option is available as of v14.2.0-canary.53.
+
+You can enable this experimental feature & provide custom revalidation times by setting the experimental `staleTimes` flag:
+
+```js filename="next.config.js"
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  experimental: {
+    staleTimes: {
+      dynamic: 30,
+      static: 180,
+    },
+  },
+}
+
+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`](https://nextjs.org/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, **meaning shared layouts won't automatically be refetched every navigation, only the new segment data.**
+> - This doesn't change back/forward caching behavior to prevent layout shift & to prevent losing scroll position.
+
+You can learn more about the Client Router Cache [here](/docs/app/building-your-application/caching#router-cache).