Skip to content

Commit

Permalink
Docs: Address internal use cache comments (#71981)
Browse files Browse the repository at this point in the history
  • Loading branch information
delbaoliveira authored and kdy1 committed Oct 30, 2024
1 parent 464fd40 commit c944da3
Showing 1 changed file with 13 additions and 15 deletions.
28 changes: 13 additions & 15 deletions docs/02-app/02-api-reference/01-directives/use-cache.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -29,11 +29,9 @@ const nextConfig: 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.

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.
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.

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.

Expand Down Expand Up @@ -69,9 +67,9 @@ export async function getData() {
## 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.
- [`cacheTag`](#revalidate-on-demand-with-cachetag): For on-demand revalidation.
Expand Down Expand Up @@ -150,7 +148,7 @@ The string values used to reference cache profiles don't carry inherent meaning;

### 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"
const nextConfig = {
Expand Down Expand Up @@ -205,7 +203,7 @@ const 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:

Expand All @@ -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`

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:**

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
3. Inner caches at two levels deep, do not affect the outer cache since they have already provided their duration to their parent.
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.

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.

Expand Down Expand Up @@ -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.

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 {
unstable_cacheTag as cacheTag,
unstable_cacheLife as cacheLife,
Expand All @@ -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'

import { revalidateTag } from 'next/cache'
Expand Down

0 comments on commit c944da3

Please sign in to comment.