Unverified Commit 256b662c authored by Delba de Oliveira's avatar Delba de Oliveira Committed by GitHub

Docs: Address internal `use cache` comments (#71981)

Related:
https://linear.app/vercel/issue/NDX-402/address-use-cache-feedback

Thank you for the review
[@timeyoutakeit](https://github.com/timeyoutakeit) ❤️
parent 3f2d2f69
...@@ -29,11 +29,9 @@ const nextConfig: NextConfig = { ...@@ -29,11 +29,9 @@ const nextConfig: NextConfig = {
export default nextConfig export default nextConfig
``` ```
> The `use cache` directive will be available separately from the`dynamicIO` flag in the future. > The `use cache` directive will be available separately from the `dynamicIO` flag in the future.
Caching is a technique to improve the performance of web applications by storing the results of computations or data fetches. In Next.js you can use caching to optimize your applications rendering performance. Caching is a technique used to improve the performance of web applications by storing the results of rendering or data requests. Whenever you use an asynchronous function or APIs that depend on request-time data, Next.js will automatically opt into dynamic rendering. You can explicitly cache the results of these operations and optimize your application's rendering performance with the `use cache` directive.
To explicitly cache certain asynchronous operations and achieve static behavior, you can use the `use cache` directive. This allows you to optimize rendering performance by caching results from async data requests, while still enabling dynamic rendering when needed.
The `use cache` directive is an experimental feature that aims to replace the [`unstable_cache`](/docs/app/api-reference/legacy-apis/unstable_cache) function. Unlike `unstable_cache`, which is limited to caching JSON data and requires manual definition of revalidation periods and tags, `use cache` offers more flexibility. It allows you to cache a wider range of data, including anything that React Server Components (RSC) can serialize, as well as data-fetching outputs and component outputs. The `use cache` directive is an experimental feature that aims to replace the [`unstable_cache`](/docs/app/api-reference/legacy-apis/unstable_cache) function. Unlike `unstable_cache`, which is limited to caching JSON data and requires manual definition of revalidation periods and tags, `use cache` offers more flexibility. It allows you to cache a wider range of data, including anything that React Server Components (RSC) can serialize, as well as data-fetching outputs and component outputs.
...@@ -69,9 +67,9 @@ export async function getData() { ...@@ -69,9 +67,9 @@ export async function getData() {
## Revalidating ## Revalidating
By default when using the `use cache` directive Next.js sets a **[revalidation period](/docs/app/building-your-application/data-fetching/fetching#revalidating-cached-data) of fifteen minutes** with a near infinite expiration duration, meaning it's suitable for content that doesn't need frequent updates. By default, Next.js sets a **[revalidation period](/docs/app/building-your-application/data-fetching/fetching#revalidating-cached-data) of 15 minutes** when you use the `use cache` directive. Next.js sets a with a near-infinite expiration duration, meaning it's suitable for content that doesn't need frequent updates.
While this may be useful for content you don't expect to change often, you can use the `cacheLife` and `cacheTag` APIs for more granular caching control: While this revalidation period may be useful for content you don't expect to change often, you can use the `cacheLife` and `cacheTag` APIs to configure the cache behavior:
- [`cacheLife`](#time-based-revalidation-with-cachelife): For time-based revalidation periods. - [`cacheLife`](#time-based-revalidation-with-cachelife): For time-based revalidation periods.
- [`cacheTag`](#revalidate-on-demand-with-cachetag): For on-demand revalidation. - [`cacheTag`](#revalidate-on-demand-with-cachetag): For on-demand revalidation.
...@@ -150,7 +148,7 @@ The string values used to reference cache profiles don't carry inherent meaning; ...@@ -150,7 +148,7 @@ The string values used to reference cache profiles don't carry inherent meaning;
### Defining reusable cache profiles ### Defining reusable cache profiles
To create a reusable cache profile, choose a name that suits your use case. You can create as many custom cache profiles as needed. Each profile can be referenced by its name as a string value passed to the `cacheLife` function. You can create a reusable cache profile by defining them in your `next.config.ts` file. Choose a name that suits your use case and set values for the `stale`, `revalidate`, and `expire` properties. You can create as many custom cache profiles as needed. Each profile can be referenced by its name as a string value passed to the `cacheLife` function.
```ts filename="next.config.ts" ```ts filename="next.config.ts"
const nextConfig = { const nextConfig = {
...@@ -205,7 +203,7 @@ const nextConfig = { ...@@ -205,7 +203,7 @@ const nextConfig = {
module.exports = nextConfig module.exports = nextConfig
``` ```
### Defining inlining cache profiles ### Defining cache profiles inline
For specific use cases, you can set a custom cache profile by passing an object to the `cacheLife` function: For specific use cases, you can set a custom cache profile by passing an object to the `cacheLife` function:
...@@ -226,13 +224,13 @@ This inline cache profile will only be applied to the function or file it was cr ...@@ -226,13 +224,13 @@ This inline cache profile will only be applied to the function or file it was cr
### Nested usage of `use cache` and `cacheLife` ### Nested usage of `use cache` and `cacheLife`
When defining multiple caching behaviors, in the same route or component tree, if the inner caches specify their own `cacheLife` profile, the outer cache will respect the shortest cache duration among them. **This applies only if the outer cache does not have its own explicit `cacheLife` profile defined.** When defining multiple caching behaviors in the same route or component tree, if the inner caches specify their own `cacheLife` profile, the outer cache will respect the shortest cache duration among them. **This applies only if the outer cache does not have its own explicit `cacheLife` profile defined.**
**Decision hierarchy for cache boundaries:** **Decision hierarchy for cache boundaries:**
1. Next.js will use the shortest cache profile found within the whole `use cache` boundary, excluding inner `use cache` directives. 1. Next.js will use the shortest cache profile found within the whole `use cache` boundary, excluding inner `use cache` directives.
2. If no cache profile exists then the shortest profile times from all inner `use cache` calls applies to this `use cache`. If there are no inner `use cache`'s then the default is used 2. If no cache profile exists, then the shortest profile times from all inner `use cache` calls applies to this `use cache`. If there are no inner `use cache`'s then the default is used
3. Inner caches at two levels deep, do not affect the outer cache since they have already provided their duration to their parent. 3. Inner caches at two levels deep do not affect the outer cache since they have already provided their duration to their parent.
For example, if you add the `use cache` directive to your page, without specifying a cache profile, the default cache profile will be applied implicitly (`cacheLife(”default”)`). If a component imported into the page also uses the `use cache` directive with its own cache profile, the outer and inner cache profiles are compared, and shortest duration set in the profiles will be applied. For example, if you add the `use cache` directive to your page, without specifying a cache profile, the default cache profile will be applied implicitly (`cacheLife(”default”)`). If a component imported into the page also uses the `use cache` directive with its own cache profile, the outer and inner cache profiles are compared, and shortest duration set in the profiles will be applied.
...@@ -272,9 +270,9 @@ export async function ChildComponent() { ...@@ -272,9 +270,9 @@ export async function ChildComponent() {
A `cacheTag` is used in combination with [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) to purge cache data, on-demand. The `cacheTag` function takes a single string value, or a string array. A `cacheTag` is used in combination with [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) to purge cache data, on-demand. The `cacheTag` function takes a single string value, or a string array.
In the below example the `getData` function uses the “weeks” cache profile, and defines a `cacheTag` on the functions cached output: In the following example,the `getData` function uses the “weeks” cache profile, and defines a `cacheTag` on the functions cached output:
```tsx filename="app/actions.ts" highlight={8,9} ```tsx filename="app/actions.ts" highlight={2,9}
import { import {
unstable_cacheTag as cacheTag, unstable_cacheTag as cacheTag,
unstable_cacheLife as cacheLife, unstable_cacheLife as cacheLife,
...@@ -290,9 +288,9 @@ export async function getData() { ...@@ -290,9 +288,9 @@ export async function getData() {
} }
``` ```
You can then purge the cache on-demand using `revalidateTag` in another function, for examples, a [route handler](/docs/app/building-your-application/routing/route-handlers) or [Server Action](/docs/app/building-your-application/data-fetching/server-actions-and-mutations): You can then purge the cache on-demand using [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) API in another function, for example, a [route handler](/docs/app/building-your-application/routing/route-handlers) or [Server Action](/docs/app/building-your-application/data-fetching/server-actions-and-mutations):
```tsx filename="app/submit.ts" highlight={6,7} ```tsx filename="app/submit.ts" highlight={3,7}
'use server' 'use server'
import { revalidateTag } from 'next/cache' import { revalidateTag } from 'next/cache'
......
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