docs: use cache private redo (#87111)

Author: icyJoseph

docs/01-app/03-api-reference/01-directives/use-cache-private.mdx

@@ -1,21 +1,31 @@
 ---
 title: 'use cache: private'
-description: 'Learn how to use the `"use cache: private"` directive to enable runtime prefetching of personalized content in your Next.js application.'
+description: 'Learn how to use the "use cache: private" directive to cache functions that access runtime request APIs.'
+version: experimental
 related:
   title: Related
   description: View related API references.
   links:
     - app/api-reference/directives/use-cache
     - app/api-reference/config/next-config-js/cacheComponents
-    - app/api-reference/config/next-config-js/cacheHandlers
     - app/api-reference/functions/cacheLife
     - app/api-reference/functions/cacheTag
-    - app/guides/prefetching
 ---
 
-The `'use cache: private'` directive works just like [`use cache`](/docs/app/api-reference/directives/use-cache), but allows you to use runtime APIs like cookies, headers, or search params.
+The `'use cache: private'` directive allows functions to access runtime request APIs like `cookies()`, `headers()`, and `searchParams` within a cached scope. However, results are **never stored on the server**, they're cached only in the browser's memory and do not persist across page reloads.
 
-> **Good to know:** Unlike `use cache`, private caches are not prerendered statically as they contain personalized data that is not shared between users.
+Reach for `'use cache: private'` when:
+
+- You want to cache a function that already accesses runtime data, and refactoring to [move the runtime access outside and pass values as arguments](/docs/app/getting-started/cache-components#with-runtime-data) is not practical.
+- Compliance requirements prevent storing certain data on the server, even temporarily
+
+Because this directive accesses runtime data, the function executes on every server render and is excluded from running during [static shell](/docs/app/getting-started/cache-components#how-rendering-works-with-cache-components) generation.
+
+It is **not** possible to configure custom cache handlers for `'use cache: private'`.
+
+For a comparison of the different cache directives, see [How `use cache: remote` differs from `use cache` and `use cache: private`](/docs/app/api-reference/directives/use-cache-remote#how-use-cache-remote-differs-from-use-cache-and-use-cache-private).
+
+> **Good to know**: This directive is marked as `experimental` because it depends on runtime prefetching, which is not yet stable. Runtime prefetching is an upcoming feature that will let the router prefetch past the [static shell](/docs/app/getting-started/cache-components#how-rendering-works-with-cache-components) into **any** cached scope, not just private caches.
 
 ## Usage
 
@@ -42,13 +52,21 @@ export default nextConfig
 
 Then add `'use cache: private'` to your function along with a `cacheLife` configuration.
 
+> **Good to know**: This directive is not available in Route Handlers.
+
 ### Basic example
 
+In this example, we demonstrate that you can access cookies within a `'use cache: private'` scope:
+
 ```tsx filename="app/product/[id]/page.tsx" switcher
 import { Suspense } from 'react'
 import { cookies } from 'next/headers'
 import { cacheLife, cacheTag } from 'next/cache'
 
+export async function generateStaticParams() {
+  return [{ id: '1' }]
+}
+
 export default async function ProductPage({
   params,
 }: {
@@ -81,7 +99,7 @@ async function Recommendations({ productId }: { productId: string }) {
 async function getRecommendations(productId: string) {
   'use cache: private'
   cacheTag(`recommendations-${productId}`)
-  cacheLife({ stale: 60 }) // Minimum 30 seconds required for runtime prefetch
+  cacheLife({ stale: 60 })
 
   // Access cookies within private cache functions
   const sessionId = (await cookies()).get('session-id')?.value || 'guest'
@@ -95,6 +113,10 @@ import { Suspense } from 'react'
 import { cookies } from 'next/headers'
 import { cacheLife, cacheTag } from 'next/cache'
 
+export async function generateStaticParams() {
+  return [{ id: '1' }]
+}
+
 export default async function ProductPage({ params }) {
   const { id } = await params
 
@@ -123,7 +145,7 @@ async function Recommendations({ productId }) {
 async function getRecommendations(productId) {
   'use cache: private'
   cacheTag(`recommendations-${productId}`)
-  cacheLife({ stale: 60 }) // Minimum 30 seconds required for runtime prefetch
+  cacheLife({ stale: 60 })
 
   // Access cookies within private cache functions
   const sessionId = (await cookies()).get('session-id')?.value || 'guest'
@@ -132,6 +154,8 @@ async function getRecommendations(productId) {
 }
 ```
 
+> **Good to know**: The `stale` time must be at least 30 seconds for runtime prefetching to work. See [`cacheLife` client router cache behavior](/docs/app/api-reference/functions/cacheLife#client-router-cache-behavior) for details.
+
 ## Request APIs allowed in private caches
 
 The following request-specific APIs can be used inside `'use cache: private'` functions:

docs/01-app/03-api-reference/01-directives/use-cache.mdx

@@ -1,6 +1,6 @@
 ---
 title: use cache
-description: Learn how to use the use cache directive to cache data in your Next.js application.
+description: Learn how to use the "use cache" directive to cache data in your Next.js application.
 related:
   title: Related
   description: View related API references.