Unverified Commit 07bf5809 authored by Aurora Scharff's avatar Aurora Scharff Committed by GitHub

docs: clarify unstable_cache cross-deployment persistence (#100983)

## Summary

- clarify that `use cache` replaces `unstable_cache` for most use cases,
while `unstable_cache` remains appropriate for non-`fetch` data that
must persist across deployments
- link the reported agent feedback:
https://next-maintainer-agent.vercel.tools/agent-feedback/5665

## Related guidance reviewed

- `docs/01-app/03-api-reference/01-directives/use-cache.mdx` already
recommends `unstable_cache` for cross-deployment persistence of
non-`fetch` data
- `docs/01-app/03-api-reference/01-directives/use-cache-remote.mdx`
already documents the same exception for remote cache entries
- `docs/01-app/02-guides/migrating-to-cache-components.mdx` already
states that migrating `unstable_cache` is optional and explains the
persistence difference

## Verification

- `pnpm exec prettier --ignore-path .prettierignore --check
docs/01-app/03-api-reference/04-functions/unstable_cache.mdx`
- `pnpm exec eslint --config eslint.config.mjs
docs/01-app/03-api-reference/04-functions/unstable_cache.mdx`
- `pnpm lint` (blocked by nine pre-existing unused Turbo Tasks findings
on canary)

<!-- NEXT_JS_LLM -->
parent 18415429
......@@ -3,9 +3,12 @@ title: unstable_cache
description: API Reference for the unstable_cache function.
---
{/* TODO: Remove the cross-deployment persistence guidance once `use cache: remote` entries persist across deployments. */}
> **Note:**
> This API has been replaced by [`use cache`](/docs/app/api-reference/directives/use-cache) in Next.js 16.
> We recommend opting into [Cache Components](/docs/app/getting-started/caching) and replacing `unstable_cache` with the `use cache` directive.
> For most use cases, [`use cache`](/docs/app/api-reference/directives/use-cache) replaces this API in Next.js 16. We recommend opting into [Cache Components](/docs/app/getting-started/caching) and migrating to the `use cache` directive.
>
> Continue using `unstable_cache` for non-`fetch` data that must persist across deployments. Cached entries from `use cache` and [`use cache: remote`](/docs/app/api-reference/directives/use-cache-remote) do not carry over to a new deployment because their cache keys include the build ID or `deploymentId`.
`unstable_cache` allows you to cache the results of expensive operations, like database queries, and reuse them across multiple requests.
......
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