@@ -33,8 +33,8 @@ Cache Components eliminates these tradeoffs by prerendering routes into a **stat
At build time, Next.js renders your route'scomponenttree.Aslongascomponentsdon't access network resources, certain system APIs, or require an incoming request to render, their output is **automatically added to the static shell**. Otherwise, you must choose how to handle them:
- Defer rendering to request time by wrapping components in React's[`<Suspense>`](https://react.dev/reference/react/Suspense),[showingfallbackUI](#defer-rendering-to-request-time) until the content is ready, or
-Cachetheresultusingthe[`use cache`](/docs/app/api-reference/directives/use-cache)directiveto[includeitinthestaticshell](#using-use-cache) (if no request data is needed)
- Either defer rendering to request time by wrapping components in React's[`<Suspense>`](https://react.dev/reference/react/Suspense),[showingfallbackUI](#defer-rendering-to-request-time) until the content is ready
-Orcachetheresultusingthe[`use cache`](/docs/app/api-reference/directives/use-cache)directiveto[includeitinthestaticshell](#using-use-cache) (if no request data is needed)
Becausethishappensaheadoftime,beforearequestarrives,werefertoitasprerendering.ThisgeneratesastaticshellconsistingofHTMLforinitialpageloadsandaserialized[RSCPayload](/docs/app/getting-started/server-and-client-components#on-the-server) for client-side navigation, ensuring the browser receives fully rendered content instantly whether users navigate directly to the URL or transition from another page.
Whilethe`use cache`directiveissufficientformostapplicationneeds,youmightoccasionallynoticethatcachedoperationsarere-runningmoreoftenthanexpected,orthatyourupstreamservices(CMS,databases,externalAPIs)aregettingmorehitsthanyou'd expect. This can happen because in-memory caching has inherent limitations:
Whilethe`use cache`directiveissufficientformostapplicationneeds,youmightnoticethatcachedoperationsarere-runningmoreoftenthanexpected,orthatyourupstreamservices(CMS,databases,externalAPIs)aregettingmorehitsthanyou'd expect. This can happen because `use cache` stores entries in-memory, which has inherent limitations:
- Cache entries being evicted to make room for new ones
- Memory constraints in your deployment environment
...
...
@@ -22,7 +22,7 @@ While the `use cache` directive is sufficient for most application needs, you mi
Note that `use cache` still provides value beyond server-side caching: it informs Next.js what can be prefetched and defines stale times for client-side navigation.
The `'usecache:remote'` directive lets you declaratively specify that a cached output should be stored in a **remote cache** instead of in-memory. While this gives you more durable caching for specific operations, it comes with tradeoffs: infrastructure cost and network latency during cache lookups.
The `'usecache:remote'` directive lets you declaratively specify that a cached output should be stored in a remote cache instead of in-memory, providing durable caching shared across all server instances. This comes with tradeoffs: infrastructure cost and network latency during cache lookups.
## Usage
...
...
@@ -73,7 +73,7 @@ Compelling scenarios for `'use cache: remote'`:
In these cases, the cost and latency of remote caching is justified by avoiding worse outcomes (rate limit errors, backend overload, high compute bills, or degraded user experience).
For static shell content, `use cache` is usually sufficient. However, if your static pages share data from an upstream that can'thandleconcurrentrevalidationrequests(likearate-limitedCMS),`use cache: remote`actsasasharedcachelayerinfrontofthatupstream.Thisisthesamepatternasputtingakey-valuestoreinfrontofadatabase,butdeclaredinyourcoderatherthanconfiguredininfrastructure.
For static shell content, `use cache` is usually sufficient. If your upstream source can'thandleconcurrentrevalidationrequests(likearate-limitedCMS),`use cache: remote`actsasasharedcachelayer.Thisisthesamepatternasputtingakey-valuestoreinfrontofadatabase,butdeclaredincode.
### How `use cache: remote` differs from `use cache` and `use cache: private`
...
...
@@ -90,9 +90,13 @@ Next.js provides three caching directives, each designed for different use cases
### Caching with runtime data
Both`use cache`and`'use cache: remote'`directivescan't access runtime data like cookies or search params directly, since this data isn'tavailablewhencomputingthecache.However,youcanextractvaluesfromtheseAPIsandpassthemasargumentstocachedfunctions.See[withruntimedata](/docs/app/getting-started/cache-components#with-runtime-data) for this pattern.
Both`use cache`and`'use cache: remote'`can't access runtime values like cookies or search params directly. You can extract these values and pass them as arguments to cached functions. See [with runtime data](/docs/app/getting-started/cache-components#with-runtime-data) for this pattern.
> **Good to know**: `use cache` stores entries in-memory. In serverless environments, memory is not shared between instances and is typically destroyed after serving a request, leading to frequent cache misses for runtime caching.
### Cache key considerations
Be thoughtful about which values you include in cache keys. Each unique value creates a separate cache entry, reducing cache utilization. Consider this example with search filters: