Unverified Commit e513488d authored by MK's avatar MK Committed by GitHub

docs: clarify serverless runtime behavior for use cache (#92232)

## Summary
- add a prominent note in the App Router Caching guide about runtime
behavior on serverless deployments
- clarify that `use cache` runtime entries are in-memory and may not
persist across requests when requests hit different instances
- link directly to `use cache: remote` as the durable/shared runtime
caching option

Closes #91959

## Verification
- **Manual/source verification**
- Confirmed before change there was no mention of serverless runtime
cache persistence in `docs/app/getting-started/caching`.
- Confirmed after change the new callout appears immediately under the
existing “Good to know” note in
`docs/01-app/01-getting-started/08-caching.mdx`.
- **Evidence screenshots (before/after + verification)**
- Before:
https://raw.githubusercontent.com/wwenrr/pr-evidence-images/main/next.js/issue-91959/2026-04-01/before.png
- After:
https://raw.githubusercontent.com/wwenrr/pr-evidence-images/main/next.js/issue-91959/2026-04-01/after.png
- Verification keyword check:
https://raw.githubusercontent.com/wwenrr/pr-evidence-images/main/next.js/issue-91959/2026-04-01/verification.png

## Notes
- Formatting toolchain was not run in this environment because `pnpm` is
unavailable on host (`pnpm: not found`).
- Change is a minimal docs-only edit (single file, two inserted lines in
a callout block).

---------
Co-authored-by: 's avatarwwenrr <wwenrr@users.noreply.github.com>
Co-authored-by: 's avatarJoseph Chamochumbi <joseph.chamochumbi@vercel.com>
Co-authored-by: 's avatarJoseph <sephxd1234@gmail.com>
parent 68d6729f
...@@ -192,6 +192,8 @@ async function CachedContent({ sessionId }: { sessionId: string }) { ...@@ -192,6 +192,8 @@ async function CachedContent({ sessionId }: { sessionId: string }) {
At request time, `CachedContent` executes if no matching cache entry is found, and stores the result for future requests with the same `sessionId`. At request time, `CachedContent` executes if no matching cache entry is found, and stores the result for future requests with the same `sessionId`.
By default, `use cache` stores entries [in-memory](/docs/app/api-reference/directives/use-cache#runtime-caching-considerations). In serverless environments where memory doesn't persist across requests, `CachedContent` may re-evaluate on every request. Consider [`'use cache: remote'`](/docs/app/api-reference/directives/use-cache-remote) for durable, shared caching.
## Working with non-deterministic operations ## Working with non-deterministic operations
Operations like `Math.random()`, `Date.now()`, or `crypto.randomUUID()` produce different values each time they execute. Cache Components requires you to explicitly handle these. Operations like `Math.random()`, `Date.now()`, or `crypto.randomUUID()` produce different values each time they execute. Cache Components requires you to explicitly handle these.
......
...@@ -192,3 +192,5 @@ See the [`revalidatePath` API reference](/docs/app/api-reference/functions/reval ...@@ -192,3 +192,5 @@ See the [`revalidatePath` API reference](/docs/app/api-reference/functions/reval
Cache data that doesn't depend on [runtime data](/docs/app/getting-started/caching#working-with-runtime-apis) and that you're OK serving from cache for a period of time. Use `use cache` with `cacheLife` to describe that behavior. Cache data that doesn't depend on [runtime data](/docs/app/getting-started/caching#working-with-runtime-apis) and that you're OK serving from cache for a period of time. Use `use cache` with `cacheLife` to describe that behavior.
For content management systems with update mechanisms, use tags with longer cache durations and rely on `revalidateTag` to refresh content when it actually changes, rather than expiring the cache preemptively. For content management systems with update mechanisms, use tags with longer cache durations and rely on `revalidateTag` to refresh content when it actually changes, rather than expiring the cache preemptively.
> **Good to know:** In serverless environments, in-memory cache entries may not persist across revalidations. See [runtime caching considerations](/docs/app/api-reference/directives/use-cache#runtime-caching-considerations) for details.
...@@ -201,9 +201,11 @@ Runtime cache behavior depends on your hosting environment: ...@@ -201,9 +201,11 @@ Runtime cache behavior depends on your hosting environment:
| Environment | Runtime Caching Behavior | | Environment | Runtime Caching Behavior |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Serverless** | Cache entries typically don't persist across requests (each request can be a different instance). Build-time caching works normally. | | **Serverless** | Cache entries typically don't persist across requests (each request can be a different instance), or during revalidation. Build-time caching works normally. |
| **Self-hosted** | Cache entries persist across requests. Control cache size with [`cacheMaxMemorySize`](/docs/app/api-reference/config/next-config-js/incrementalCacheHandlerPath). | | **Self-hosted** | Cache entries persist across requests. Control cache size with [`cacheMaxMemorySize`](/docs/app/api-reference/config/next-config-js/incrementalCacheHandlerPath). |
For example, in a serverless environment, a cached function shared by two pages executes on each static shell revalidation, whereas in self-hosted or environments with persistent memory, the cached output is reused if it's still fresh.
If the default in-memory cache isn't enough, consider **[`use cache: remote`](/docs/app/api-reference/directives/use-cache-remote)** which allows platforms to provide a dedicated cache handler (like Redis or KV database). This helps reduce hits against data sources not scaled to your total traffic, though it comes with costs (storage, network latency, platform fees). If the default in-memory cache isn't enough, consider **[`use cache: remote`](/docs/app/api-reference/directives/use-cache-remote)** which allows platforms to provide a dedicated cache handler (like Redis or KV database). This helps reduce hits against data sources not scaled to your total traffic, though it comes with costs (storage, network latency, platform fees).
Very rarely, for compliance requirements or when you can't refactor your code to pass runtime data as arguments to a `use cache` scope, you might need [`use cache: private`](/docs/app/api-reference/directives/use-cache-private). Very rarely, for compliance requirements or when you can't refactor your code to pass runtime data as arguments to a `use cache` scope, you might need [`use cache: private`](/docs/app/api-reference/directives/use-cache-private).
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment