use cache: remote

While the use cache directive is sufficient for most application needs, you might notice that cached operations are re-running more often than expected, or that your upstream services (CMS, databases, external APIs) are getting more hits than you'd expect. This can happen because use cache stores entries in-memory, which has inherent limitations:
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 'use cache: 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.
To use 'use cache: remote', enable the cacheComponents flag in your next.config.ts file:
Then add 'use cache: remote' to the functions or components where you've determined remote caching is justified. The handler implementation is configured via cacheHandlers, though hosting providers should typically provide this automatically. If you're self-hosting, see the cacheHandlers configuration reference to set up your cache storage.
Remote caching provides the most value when content is deferred to request time (outside the static shell). This typically happens when a component accesses request values like cookies(), headers(), or searchParams, placing it inside a Suspense boundary. In this context:
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. If your upstream source can't handle concurrent revalidation requests (like a rate-limited CMS), use cache: remote acts as a shared cache layer. This is the same pattern as putting a key-value store in front of a database, but declared in code.
Next.js provides three caching directives, each designed for different use cases:
Remote cache entries do not persist across deploys. The cache key includes the deploymentId (when configured) or the buildId, so a new build produces new keys and the previous build's entries are no longer reachable. See Cache keys for the full key composition.
This is intentional. Between builds, the function's identity hash or the shape of its return value can change. Upgrading a CMS client, refactoring a cached function, or changing a dependency could produce a value that doesn't match what older callers expect, so reusing entries across deploys risks serving stale or malformed data.
If you need entries that persist across deploys, use unstable_cache for non-fetch functions, or rely on the fetch cache.
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 for this pattern.
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.
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:
In this example, the remote handler stores more data per cache entry (all products in a category) to achieve better cache hit rates. This is worth it when the cost of cache misses (hitting your backend) outweighs the storage cost of larger entries.
The same principle applies to user-specific data. Rather than caching per-user data directly, use user preferences to determine what shared data to cache.
For example, if users have a language preference in their session, extract that preference and use it to cache shared content:
This way all users who prefer the same language share a cache entry, improving cache utilization and reducing load on your CMS.
The pattern is the same in both examples: find the dimension with fewer unique values (category vs. price, language vs. user ID), cache on that dimension, and filter or select the rest in memory.
If the service used by getUserProfile cannot scale with your frontend load, you may still be able to use the use cache directive with a short cacheLife for in-memory caching. However, for most user data, you likely want to fetch directly from the source (which might already be wrapped in a key/value store as mentioned in the guidelines above).
Only use 'use cache: private' if you have compliance requirements or can't refactor to pass runtime data as arguments.
Remote caches have specific nesting rules:
The following examples demonstrate common patterns for using 'use cache: remote'. For details about cacheLife parameters (stale, revalidate, expire), see the cacheLife API reference.
Cache product pricing based on the user's currency preference. Since the currency is stored in a cookie, this component renders at request time. Remote caching is valuable here because all users with the same currency share the cached price, and in serverless environments, all instances share the same remote cache.
Cache expensive database queries, reducing load on your database. In this example, we don't access cookies(), headers(), or searchParams. If we had a requirement to not include these stats in the static shell, we could use connection() to explicitly defer to request time:
With this setup, your upstream database sees at most one request per minute, regardless of how many users visit the dashboard.
Cache API responses that are fetched during streaming or after dynamic operations:
Cache expensive computations that occur after dynamic security or feature checks:
Combine static, remote, and private caching for optimal performance:
View related API references.
Last updated August