Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve Unstable Cache Docs #65942

Merged
merged 10 commits into from
Jul 1, 2024
44 changes: 42 additions & 2 deletions docs/02-app/02-api-reference/04-functions/unstable_cache.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Arinji2 marked this conversation as resolved.
Show resolved Hide resolved
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 |
Expand Down
Loading