Skip to content

Commit 256b662

Browse files
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) ❤️
1 parent 3f2d2f6 commit 256b662

File tree

1 file changed

+13
-15
lines changed

1 file changed

+13
-15
lines changed

docs/02-app/02-api-reference/01-directives/use-cache.mdx

Lines changed: 13 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -29,11 +29,9 @@ const nextConfig: NextConfig = {
2929
export default nextConfig
3030
```
3131

32-
> The `use cache` directive will be available separately from the`dynamicIO` flag in the future.
32+
> The `use cache` directive will be available separately from the `dynamicIO` flag in the future.
3333
34-
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.
35-
36-
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.
34+
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.
3735

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

@@ -69,9 +67,9 @@ export async function getData() {
6967
7068
## Revalidating
7169

72-
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.
70+
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.
7371

74-
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:
72+
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:
7573

7674
- [`cacheLife`](#time-based-revalidation-with-cachelife): For time-based revalidation periods.
7775
- [`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;
150148

151149
### Defining reusable cache profiles
152150

153-
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.
151+
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.
154152

155153
```ts filename="next.config.ts"
156154
const nextConfig = {
@@ -205,7 +203,7 @@ const nextConfig = {
205203
module.exports = nextConfig
206204
```
207205

208-
### Defining inlining cache profiles
206+
### Defining cache profiles inline
209207

210208
For specific use cases, you can set a custom cache profile by passing an object to the `cacheLife` function:
211209

@@ -226,13 +224,13 @@ This inline cache profile will only be applied to the function or file it was cr
226224

227225
### Nested usage of `use cache` and `cacheLife`
228226

229-
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.**
227+
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.**
230228

231229
**Decision hierarchy for cache boundaries:**
232230

233231
1. Next.js will use the shortest cache profile found within the whole `use cache` boundary, excluding inner `use cache` directives.
234-
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
235-
3. Inner caches at two levels deep, do not affect the outer cache since they have already provided their duration to their parent.
232+
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
233+
3. Inner caches at two levels deep do not affect the outer cache since they have already provided their duration to their parent.
236234

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

@@ -272,9 +270,9 @@ export async function ChildComponent() {
272270

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

275-
In the below example the `getData` function uses the “weeks” cache profile, and defines a `cacheTag` on the functions cached output:
273+
In the following example,the `getData` function uses the “weeks” cache profile, and defines a `cacheTag` on the functions cached output:
276274

277-
```tsx filename="app/actions.ts" highlight={8,9}
275+
```tsx filename="app/actions.ts" highlight={2,9}
278276
import {
279277
unstable_cacheTag as cacheTag,
280278
unstable_cacheLife as cacheLife,
@@ -290,9 +288,9 @@ export async function getData() {
290288
}
291289
```
292290

293-
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):
291+
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):
294292

295-
```tsx filename="app/submit.ts" highlight={6,7}
293+
```tsx filename="app/submit.ts" highlight={3,7}
296294
'use server'
297295

298296
import { revalidateTag } from 'next/cache'

0 commit comments

Comments
 (0)