From 8e756d6665dc1e3eb7ea59e4bdb194f994963273 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          | 42 +++++++++++++++++++
 2 files changed, 44 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..5e76c4c6803a6
--- /dev/null
+++ b/docs/02-app/02-api-reference/05-next-config-js/staleTimes.mdx
@@ -0,0 +1,42 @@
+---
+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.
+> - 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).