docs: edits to use-cache-remote (#85168)

Author: icyJoseph

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

@@ -11,11 +11,15 @@ related:
     - app/api-reference/config/next-config-js/cacheComponents
     - app/api-reference/functions/cacheLife
     - app/api-reference/functions/cacheTag
+    - app/api-reference/functions/connection
 ---
 
-The `'use cache: remote'` directive enables caching in dynamic contexts where regular `use cache` would not work, such as after calling `await connection()`, `await cookies()`, or `await headers()`.
+The `'use cache: remote'` directive enables caching of **shared data** in dynamic contexts where regular [`use cache`](/docs/app/api-reference/directives/use-cache) would not work, for example after calling [`await connection()`](/docs/app/api-reference/functions/connection), [`cookies()`](/docs/app/api-reference/functions/cookies) or [`headers()`](/docs/app/api-reference/functions/headers).
 
-> **Good to know:** `'use cache: remote'` is a variant of [`use cache`](/docs/app/api-reference/directives/use-cache) designed specifically for runtime caching in dynamic contexts. Unlike regular `use cache`, it works after dynamic data access and stores results in server-side cache handlers.
+> **Good to know:**
+>
+> - Results are stored in server-side cache handlers and shared across all users.
+> - For **user-specific data** that depends on [`cookies()`](/docs/app/api-reference/functions/cookies) or [`headers()`](/docs/app/api-reference/functions/headers), use [`'use cache: private'`](/docs/app/api-reference/directives/use-cache-private) instead to avoid accidentally sharing personalized data between users.
 
 ## Usage
 
@@ -67,13 +71,13 @@ export default async function ProductPage({
 }
 
 async function ProductPrice({ productId }: { productId: string }) {
-  // Ensure this component is never cached in the static shell
-  // by requiring a connection. This makes it dynamic.
+  // Calling connection() makes this component dynamic, preventing
+  // it from being included in the static shell. This ensures the price
+  // is always fetched at request time.
   await connection()
 
-  // Since we're in a dynamic context (after connection()),
-  // using "use cache" would NOT cache at all. We need "use cache: remote"
-  // to cache at runtime in a remote cache handler.
+  // Now we can cache the price in a remote cache handler.
+  // Regular 'use cache' would NOT work here because we're in a dynamic context.
   const price = await getProductPrice(productId)
 
   return <div>Price: ${price}</div>
@@ -82,8 +86,11 @@ async function ProductPrice({ productId }: { productId: string }) {
 async function getProductPrice(productId: string) {
   'use cache: remote'
   cacheTag(`product-price-${productId}`)
-  cacheLife({ stale: 3600 }) // 1 hour
 
+  // Client uses cached value for 1 hour
+  cacheLife({ stale: 3600 })
+
+  // This database query is cached and shared across all users
   return db.products.getPrice(productId)
 }
 ```
@@ -107,13 +114,13 @@ export default async function ProductPage({ params }) {
 }
 
 async function ProductPrice({ productId }) {
-  // Ensure this component is never cached in the static shell
-  // by requiring a connection. This makes it dynamic.
+  // Calling connection() makes this component dynamic, preventing
+  // it from being included in the static shell. This ensures the price
+  // is always fetched at request time.
   await connection()
 
-  // Since we're in a dynamic context (after connection()),
-  // using "use cache" would NOT cache at all. We need "use cache: remote"
-  // to cache at runtime in a remote cache handler.
+  // Now we can cache the price in a remote cache handler.
+  // Regular 'use cache' would NOT work here because we're in a dynamic context.
   const price = await getProductPrice(productId)
 
   return <div>Price: ${price}</div>
@@ -122,13 +129,16 @@ async function ProductPrice({ productId }) {
 async function getProductPrice(productId) {
   'use cache: remote'
   cacheTag(`product-price-${productId}`)
-  cacheLife({ stale: 3600 }) // 1 hour
 
+  // Client uses cached value for 1 hour
+  cacheLife({ stale: 3600 })
+
+  // This database query is cached and shared across all users
   return db.products.getPrice(productId)
 }
 ```
 
-> **Note:** Regular `use cache` will not cache anything when used in a dynamic context (after `await connection()`, `await cookies()`, `await headers()`, etc.). Use `'use cache: remote'` to enable runtime caching in these scenarios.
+> **Note:** Regular [`use cache`](/docs/app/api-reference/directives/use-cache) will not cache anything when used in a [dynamic context](/docs/app/getting-started/partial-prerendering#dynamic-rendering) (after [`await connection()`](/docs/app/api-reference/functions/connection), [`await cookies()`](/docs/app/api-reference/functions/cookies), [`await headers()`](/docs/app/api-reference/functions/headers), etc.). Use `'use cache: remote'` to enable runtime caching in these scenarios.
 
 ## Difference from `use cache` and `use cache: private`
 
@@ -147,15 +157,33 @@ Next.js provides three caching directives, each designed for different use cases
 
 ### When to use each
 
-- **`use cache`**: Use for static content that can be prerendered at build time and doesn't depend on request-specific data.
-- **`'use cache: remote'`**: Use when caching is needed after dynamic data access (`connection()`) or for per-request caching of shared data.
-- **`'use cache: private'`**: Use for user-specific content that needs to be runtime prefetched and depends on cookies, headers, or search params.
+Choose the right caching directive based on your use case:
+
+**Use [`use cache`](/docs/app/api-reference/directives/use-cache) when:**
+
+- Content can be [prerendered at build time](/docs/app/getting-started/partial-prerendering)
+- Content is shared across all users
+- Content doesn't depend on request-specific data
+
+**Use `'use cache: remote'` when:**
+
+- You need caching within [dynamic rendering](/docs/app/getting-started/partial-prerendering#dynamic-rendering)
+- Content is shared across users but must be rendered per-request
+- You want to cache expensive operations in a server-side cache handler
+
+**Use [`'use cache: private'`](/docs/app/api-reference/directives/use-cache-private) when:**
+
+- Content is personalized per-user (depends on cookies, headers)
+- You need [runtime prefetching](/docs/app/guides/prefetching) of user-specific content
+- Content should never be shared between users
 
 ## How it works
 
+The `'use cache: remote'` directive enables runtime caching of shared data in dynamic contexts by storing results in server-side cache handlers rather than prerendering at build time.
+
 ### Dynamic context detection
 
-When Next.js encounters certain APIs like `connection()`, `cookies()`, or `headers()`, the context becomes "dynamic". In a dynamic context:
+When Next.js encounters certain APIs like [`connection()`](/docs/app/api-reference/functions/connection), [`cookies()`](/docs/app/api-reference/functions/cookies), or [`headers()`](/docs/app/api-reference/functions/headers), the context becomes "[dynamic](/docs/app/getting-started/partial-prerendering#dynamic-rendering)". In a dynamic context:
 
 1. **Regular `use cache` stops working** - it won't cache anything
 2. **`'use cache: remote'` continues to work** - it caches in the remote cache handler
@@ -176,21 +204,21 @@ This means:
 
 1. Cached data is shared across all users and requests
 2. Cache entries persist beyond a single session
-3. Cache invalidation works via `cacheTag` and `revalidateTag`
-4. Cache expiration is controlled by `cacheLife` configuration
+3. Cache invalidation works via [`cacheTag`](/docs/app/api-reference/functions/cacheTag) and [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag)
+4. Cache expiration is controlled by [`cacheLife`](/docs/app/api-reference/functions/cacheLife) configuration
 
 ### Dynamic context example
 
 ```tsx
 async function UserDashboard() {
-  // This call makes the context dynamic
+  // Calling connection() makes the context dynamic
   await connection()
 
-  // Regular 'use cache' would NOT cache here
-  const stats = await getStats() // Not cached with 'use cache'
+  // Without any caching directive, this runs on every request
+  const stats = await getStats()
 
-  // But 'use cache: remote' WILL cache here
-  const analytics = await getAnalytics() // Cached with 'use cache: remote'
+  // With 'use cache: remote', this is cached in the remote handler
+  const analytics = await getAnalytics()
 
   return (
     <div>
@@ -202,21 +230,25 @@ async function UserDashboard() {
 
 async function getAnalytics() {
   'use cache: remote'
-  cacheLife({ stale: 300 }) // 5 minutes
+
+  // Client uses cached value for 5 minutes
+  cacheLife({ stale: 300 })
+
+  // This expensive operation is cached and shared across all requests
   return fetchAnalyticsData()
 }
 ```
 
 ## Request APIs and remote caches
 
-While `'use cache: remote'` technically allows access to request-specific APIs like `cookies()` and `headers()`, it's generally not recommended to use them together:
+While `'use cache: remote'` technically allows access to request-specific APIs like [`cookies()`](/docs/app/api-reference/functions/cookies) and [`headers()`](/docs/app/api-reference/functions/headers), it's generally not recommended to use them together:
 
-| API            | Allowed in `use cache` | Allowed in `'use cache: remote'` | Recommended                        |
-| -------------- | ---------------------- | -------------------------------- | ---------------------------------- |
-| `cookies()`    | No                     | Yes (not recommended)            | Use `'use cache: private'` instead |
-| `headers()`    | No                     | Yes (not recommended)            | Use `'use cache: private'` instead |
-| `connection()` | No                     | Yes                              | Yes - this is the primary use case |
-| `searchParams` | No                     | Yes (not recommended)            | Use `'use cache: private'` instead |
+| API                                                                                   | Allowed in `use cache` | Allowed in `'use cache: remote'` | Recommended                                                                                |
+| ------------------------------------------------------------------------------------- | ---------------------- | -------------------------------- | ------------------------------------------------------------------------------------------ |
+| [`cookies()`](/docs/app/api-reference/functions/cookies)                              | No                     | Yes (not recommended)            | Use [`'use cache: private'`](/docs/app/api-reference/directives/use-cache-private) instead |
+| [`headers()`](/docs/app/api-reference/functions/headers)                              | No                     | Yes (not recommended)            | Use [`'use cache: private'`](/docs/app/api-reference/directives/use-cache-private) instead |
+| [`connection()`](/docs/app/api-reference/functions/connection)                        | No                     | Yes                              | Yes - this is the primary use case                                                         |
+| [`searchParams`](/docs/app/api-reference/file-conventions/page#searchparams-optional) | No                     | Yes (not recommended)            | Use [`'use cache: private'`](/docs/app/api-reference/directives/use-cache-private) instead |
 
 > **Important:** If you need to cache based on cookies, headers, or search params, use [`'use cache: private'`](/docs/app/api-reference/directives/use-cache-private) instead. Remote caches are shared across all users, so caching user-specific data in them can lead to incorrect results being served to different users.
 
@@ -302,9 +334,12 @@ export default async function DashboardPage() {
 async function getGlobalStats() {
   'use cache: remote'
   cacheTag('global-stats')
-  cacheLife({ stale: 60 }) // 1 minute
 
-  // Expensive database query - cached for all users
+  // Client uses cached value for 1 minute
+  cacheLife({ stale: 60 })
+
+  // This expensive database query is cached and shared across all users,
+  // reducing load on your database
   const stats = await db.analytics.aggregate({
     total_users: 'count',
     active_sessions: 'count',
@@ -346,9 +381,11 @@ async function FeedItems() {
 async function getFeedItems() {
   'use cache: remote'
   cacheTag('feed-items')
-  cacheLife({ stale: 120 }) // 2 minutes
 
-  // Fetch from external API
+  // Client uses cached value for 2 minutes
+  cacheLife({ stale: 120 })
+
+  // This API call is cached, reducing requests to your external service
   const response = await fetch('https://api.example.com/feed')
   return response.json()
 }
@@ -373,9 +410,12 @@ export default async function ReportsPage() {
 
 async function generateReport() {
   'use cache: remote'
-  cacheLife({ stale: 3600 }) // 1 hour
 
-  // Expensive computation - shared across all authorized users
+  // Client uses cached value for 1 hour
+  cacheLife({ stale: 3600 })
+
+  // This expensive computation is cached and shared across all authorized users,
+  // avoiding repeated calculations
   const data = await db.transactions.findMany()
 
   return {
@@ -395,27 +435,35 @@ import { Suspense } from 'react'
 import { cookies, connection } from 'next/server'
 import { cacheLife, cacheTag } from 'next/cache'
 
-// Static product data (build-time cache)
+// Static product data - prerendered at build time
 async function getProduct(id: string) {
   'use cache'
   cacheTag(`product-${id}`)
+
+  // This is cached at build time and shared across all users
   return db.products.find({ where: { id } })
 }
 
-// Shared pricing data (runtime remote cache)
+// Shared pricing data - cached at runtime in remote handler
 async function getProductPrice(id: string) {
   'use cache: remote'
   cacheTag(`product-price-${id}`)
-  cacheLife({ stale: 300 }) // 5 minutes
+
+  // Client uses cached value for 5 minutes
+  cacheLife({ stale: 300 })
+
+  // This is cached at runtime and shared across all users
   return db.products.getPrice({ where: { id } })
 }
 
-// User-specific recommendations (private cache)
+// User-specific recommendations - private cache per user
 async function getRecommendations(productId: string) {
   'use cache: private'
   cacheLife({ stale: 60 })
 
   const sessionId = (await cookies()).get('session-id')?.value
+
+  // This is cached per-user and never shared
   return db.recommendations.findMany({
     where: { productId, sessionId },
   })
@@ -445,7 +493,9 @@ export default async function ProductPage({ params }) {
 }
 
 async function ProductPriceComponent({ productId }) {
-  await connection() // Make dynamic
+  // Make this component dynamic
+  await connection()
+
   const price = await getProductPrice(productId)
   return <div>Price: ${price}</div>
 }
@@ -459,10 +509,10 @@ async function ProductRecommendations({ productId }) {
 > **Good to know**:
 >
 > - Remote caches are stored in server-side cache handlers and shared across all users
-> - Remote caches work in dynamic contexts where regular `use cache` would fail
-> - Use `cacheTag()` and `revalidateTag()` to invalidate remote caches on-demand
-> - Use `cacheLife()` to configure cache expiration
-> - For user-specific data, use `'use cache: private'` instead of `'use cache: remote'`
+> - Remote caches work in [dynamic contexts](/docs/app/getting-started/partial-prerendering#dynamic-rendering) where regular [`use cache`](/docs/app/api-reference/directives/use-cache) would fail
+> - Use [`cacheTag()`](/docs/app/api-reference/functions/cacheTag) and [`revalidateTag()`](/docs/app/api-reference/functions/revalidateTag) to invalidate remote caches on-demand
+> - Use [`cacheLife()`](/docs/app/api-reference/functions/cacheLife) to configure cache expiration
+> - For user-specific data, use [`'use cache: private'`](/docs/app/api-reference/directives/use-cache-private) instead of `'use cache: remote'`
 > - Remote caches reduce origin load by storing computed or fetched data server-side
 
 ## Platform Support