Improve Unstable Cache Docs (#65942)

Unstable Cache has always had a very lacking documentation page, even
though it adding its own new feature ``key parts`` . Its a normal
occurrence for us in the NextJS Discord to see new people and more
advanced users question what is the use of key parts, since the example
in the docs. was very lacking.

I have made a few changes, like adding a much more functional example
which showcases all the features of unstable cache, and also a small
difference section between tags and key parts.

---------

Co-authored-by: Sam Ko <sam@vercel.com>
This commit is contained in:
Arinjay Dhar 2024-07-01 17:20:51 +05:30 committed by GitHub
parent b9bd23baec
commit 303d155c08
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -34,15 +34,55 @@ const data = unstable_cache(fetchData, keyParts, options)()
```
- `fetchData`: This is an asynchronous function that fetches the data you want to cache. It must be a function that returns a `Promise`.
- `keyParts`: This is an array that identifies the cached key. It must contain globally unique values that together identify the key of the data being cached. The cache key also includes the arguments passed to the function.
- `keyParts`: This is an extra array of keys that further adds identification to the cache. By default, `unstable_cache` already uses the arguments and the stringified version of your function as the cache key. It is optional in most cases; the only time you need to use it is when you use external variables without passing them as parameters. However, it is important to add closures used within the function if you do not pass them as parameters.
- `options`: This is an object that controls how the cache behaves. It can contain the following properties:
- `tags`: An array of tags that can be used to control cache invalidation.
- `tags`: An array of tags that can be used to control cache invalidation. Next.js will not use this to uniquely identify the function.
- `revalidate`: The number of seconds after which the cache should be revalidated. Omit or pass `false` to cache indefinitely or until matching `revalidateTag()` or `revalidatePath()` methods are called.
## Returns
`unstable_cache` returns a function that when invoked, returns a Promise that resolves to the cached data. If the data is not in the cache, the provided function will be invoked, and its result will be cached and returned.
## Example
```tsx filename="app/page.tsx" switcher
import { unstable_cache } from 'next/cache';
export default async function Page({ params }: { params: { userID: string } }) {
const getCachedUser = unstable_cache(
async () => {
return { id: params.userID };
},
[params.userID], // here we add the userID in the keyParts so Next.js can make separate caches for the different userID's.
{
tags: ["cached-user-tag"],
revalidate: 60,
}
);
...
}
```
```jsx filename="app/page.jsx" switcher
import { unstable_cache } from 'next/cache';
export default async function Page({ params }) {
const getCachedUser = unstable_cache(
async () => {
return { id: params.userID };
},
[params.userID], // here we add the userID in the keyParts so Next.js can make separate caches for the different userID's.
{
tags: ["cached-user-tag"],
revalidate: 60,
}
);
...
}
```
## Version History
| Version | Changes |