Skip to content

Commit

Permalink
Clarify serialization behavior of "use cache" (vercel#72286)
Browse files Browse the repository at this point in the history
Maybe not ideal wording but this should be more correct. See
vercel#72081 (comment).

---------

Co-authored-by: Delba de Oliveira <[email protected]>
Co-authored-by: JJ Kasper <[email protected]>
  • Loading branch information
3 people authored Nov 5, 2024
1 parent b754b4e commit 0a209a9
Showing 1 changed file with 3 additions and 1 deletion.
4 changes: 3 additions & 1 deletion docs/02-app/02-api-reference/01-directives/use-cache.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,9 @@ export async function getData() {
## Good to know

- `use cache` is an experimental Next.js feature, and not a native React feature like [`use client`](/docs/app/api-reference/directives/use-client) or [`use server`](/docs/app/api-reference/directives/use-server).
- The arguments (or props) passed to a cached function must be [serializable](https://react.dev/reference/rsc/use-server#serializable-parameters-and-return-values) by React. This means they can be converted to a format like JSON. Non-serializable props like functions or React elements cannot be used as arguments.
- Any [serializable](https://react.dev/reference/rsc/use-server#serializable-parameters-and-return-values) arguments (or props) passed to the cached function, as well as any serializable values it reads from the parent scope, will be converted to a format like JSON and automatically become a part of the cache key.
- Any non-serializable arguments, props, or closed-over values will turn into opaque references inside the cached function, and can be only passed through and not inspected nor modified. These non-serializable values will be filled in at the request time and won't become a part of the cache key.
- For example, a cached function can take in JSX as a `children` prop and return `<div>{children}</div>`, but it won't be able to introspect the actual `children` object.
- The return value of the cacheable function must also be serializable. This ensures that the cached data can be stored and retrieved correctly.
- Functions that use the `use cache` directive must not have any side-effects, such as modifying state, directly manipulating the DOM, or setting timers to execute code at intervals.
- If used alongside [Partial Prerendering](/docs/app/building-your-application/rendering/partial-prerendering), segments that have `use cache` will be prerendered as part of the static HTML shell.
Expand Down

0 comments on commit 0a209a9

Please sign in to comment.