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

Docs: Fix formatting issues in the caching docs (#53436)

parent 2aee3ef0
...@@ -64,9 +64,9 @@ export default async function Page() { ...@@ -64,9 +64,9 @@ export default async function Page() {
> **Good to know**: > **Good to know**:
> >
> Next.js provides helpful functions you may need when fetching data in Server Components such as [`cookies`](/docs/app/api-reference/functions/cookies) and [`headers`](/docs/app/api-reference/functions/headers). These will cause the route to be dynamically rendered as they rely on request time information. > - Next.js provides helpful functions you may need when fetching data in Server Components such as [`cookies`](/docs/app/api-reference/functions/cookies) and [`headers`](/docs/app/api-reference/functions/headers). These will cause the route to be dynamically rendered as they rely on request time information.
> In Route handlers, `fetch` requests are not memoized as Route Handlers are not part of the React component tree. > - In Route handlers, `fetch` requests are not memoized as Route Handlers are not part of the React component tree.
> To use `async`/`await` in a Server Component with TypeScript, you'll need to use TypeScript `5.1.3` or higher and `@types/react` `18.2.8` or higher. > - To use `async`/`await` in a Server Component with TypeScript, you'll need to use TypeScript `5.1.3` or higher and `@types/react` `18.2.8` or higher.
### Caching Data ### Caching Data
...@@ -85,7 +85,7 @@ fetch('https://...', { cache: 'force-cache' }) ...@@ -85,7 +85,7 @@ fetch('https://...', { cache: 'force-cache' })
> >
> The Data Cache is a persistent [HTTP cache](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching). Depending on your platform, the cache can scale automatically and be [shared across multiple regions](https://vercel.com/docs/infrastructure/data-cache). > The Data Cache is a persistent [HTTP cache](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching). Depending on your platform, the cache can scale automatically and be [shared across multiple regions](https://vercel.com/docs/infrastructure/data-cache).
> >
> > Learn more about the [Data Cache](/docs/app/building-your-application/caching#data-cache). > Learn more about the [Data Cache](/docs/app/building-your-application/caching#data-cache).
### Revalidating Data ### Revalidating Data
...@@ -143,7 +143,7 @@ export default async function Page() { ...@@ -143,7 +143,7 @@ export default async function Page() {
If using a Route Handler, you should create a secret token only known by your Next.js app. This secret will be used to prevent unauthorized revalidation attempts. For example, you can access the route (either manually or with a webhook) with the following URL structure: If using a Route Handler, you should create a secret token only known by your Next.js app. This secret will be used to prevent unauthorized revalidation attempts. For example, you can access the route (either manually or with a webhook) with the following URL structure:
``` ```bash filename="URL"
https://<your-site.com>/api/revalidate?tag=collection&secret=<token> https://<your-site.com>/api/revalidate?tag=collection&secret=<token>
``` ```
...@@ -231,7 +231,7 @@ If an error is thrown while attempting to revalidate data, the last successfully ...@@ -231,7 +231,7 @@ If an error is thrown while attempting to revalidate data, the last successfully
To opt out of caching for individual `fetch` requests, you can set the `cache` option in `fetch` to `'no-store'`. This will fetch data dynamically, on every request. To opt out of caching for individual `fetch` requests, you can set the `cache` option in `fetch` to `'no-store'`. This will fetch data dynamically, on every request.
```js ```js filename="layout.js / page.js"
fetch('https://...', { cache: 'no-store' }) fetch('https://...', { cache: 'no-store' })
``` ```
......
...@@ -308,4 +308,6 @@ With this approach, you can eagerly fetch data, cache responses, and guarantee t ...@@ -308,4 +308,6 @@ With this approach, you can eagerly fetch data, cache responses, and guarantee t
The `utils/get-item` exports can be used by Layouts, Pages, or other components to give them control over when an item's data is fetched. The `utils/get-item` exports can be used by Layouts, Pages, or other components to give them control over when an item's data is fetched.
> **Good to know:**
>
> - We recommend using the [`server-only` package](/docs/getting-started/react-essentials#keeping-server-only-code-out-of-client-components-poisoning) to make sure server data fetching functions are never used on the client. > - We recommend using the [`server-only` package](/docs/getting-started/react-essentials#keeping-server-only-code-out-of-client-components-poisoning) to make sure server data fetching functions are never used on the client.
...@@ -104,19 +104,17 @@ Since the memoization is not shared across server requests and only applies duri ...@@ -104,19 +104,17 @@ Since the memoization is not shared across server requests and only applies duri
To opt out of memoization in `fetch` requests, you can pass an `AbortController` `signal` to the request. To opt out of memoization in `fetch` requests, you can pass an `AbortController` `signal` to the request.
```js ```js filename="app/example.js"
const { signal } = new AbortController() const { signal } = new AbortController()
fetch(url, { signal }) fetch(url, { signal })
``` ```
## Data Cache ## Data Cache
Next.js has a built-in Data Cache that **persists** the result of data fetches across incoming **server requests** and **deployments**. This is possible because Next.js extends the native `fetch` API to allow each request on the server to set its own persistent caching semantics. Next.js has a built-in Data Cache that **persists** the result of data fetches across incoming **server requests** and **deployments**. This is possible because Next.js extends the native `fetch` API to allow each request on the server to set its own persistent caching semantics. n the browser, the `cache` option of `fetch` indicates how a request will interact with the browser's HTTP cache, with Next.js, the `cache` option indicates how a server-side request will interact with the servers Data Cache.
By default, data requests that use `fetch` are **cached**. You can use the [`cache`](#fetch-optionscache) and [`next.revalidate`](#fetch-optionsnextrevalidate) options of `fetch` to configure the caching behavior. By default, data requests that use `fetch` are **cached**. You can use the [`cache`](#fetch-optionscache) and [`next.revalidate`](#fetch-optionsnextrevalidate) options of `fetch` to configure the caching behavior.
> **Good to know**: In the browser, the `cache` option of `fetch` indicates how a request will interact with the browser's HTTP cache, with Next.js, the `cache` option indicates how a server-side request will interact with the servers Data Cache.
<Image <Image
alt="Diagram showing how cached and uncached fetch requests interact with the Data Cache. Cached requests are stored in the Data Cache, and memoized, uncached requests are fetched from the data source, not stored in the Data Cache, and memoized." alt="Diagram showing how cached and uncached fetch requests interact with the Data Cache. Cached requests are stored in the Data Cache, and memoized, uncached requests are fetched from the data source, not stored in the Data Cache, and memoized."
srcLight="/docs/light/data-cache.png" srcLight="/docs/light/data-cache.png"
...@@ -216,11 +214,11 @@ export const dynamic = 'force-dynamic' ...@@ -216,11 +214,11 @@ export const dynamic = 'force-dynamic'
## Full Route Cache ## Full Route Cache
Next.js automatically renders and caches routes at build time. This is an optimization that allows you to serve the cached route instead of rendering on the server for every request, resulting in faster page loads.
> **Related terms**: > **Related terms**:
> >
> - You may see the terms **Automatic Static Optimization**, **Static Site Generation**, or **Static Rendering** being used interchangeably to refer to the process of rendering and caching routes of your application at build time. > You may see the terms **Automatic Static Optimization**, **Static Site Generation**, or **Static Rendering** being used interchangeably to refer to the process of rendering and caching routes of your application at build time.
Next.js automatically renders and caches routes at build time. This is an optimization that allows you to serve the cached route instead of rendering on the server for every request, resulting in faster page loads.
To understand how the Full Route Cache works, it's helpful to look at how React handles rendering, and how Next.js caches the result: To understand how the Full Route Cache works, it's helpful to look at how React handles rendering, and how Next.js caches the result:
...@@ -312,6 +310,11 @@ You can opt out of the Full Route Cache, or in other words, dynamically render c ...@@ -312,6 +310,11 @@ You can opt out of the Full Route Cache, or in other words, dynamically render c
## Router Cache ## Router Cache
> **Related Terms:**
>
> You may see the Router Cache being referred to as **Client-side Cache** or **Prefetch Cache**. While **Prefetch Cache** refers to the prefetched route segments, **Client-side Cache** refers to the whole Router cache, which includes both visited and prefetched segments.
> This cache specifically applies to Next.js and Server Components, and is different to the browser's [bfcache](https://web.dev/bfcache/), though it has a similar result.
Next.js has an in-memory client-side cache that stores the React Server Component Payload, split by individual route segments, for the duration of a user session. This is called the Router Cache. Next.js has an in-memory client-side cache that stores the React Server Component Payload, split by individual route segments, for the duration of a user session. This is called the Router Cache.
<Image <Image
...@@ -332,13 +335,8 @@ This results in an improved navigation experience for the user: ...@@ -332,13 +335,8 @@ This results in an improved navigation experience for the user:
> **Difference between the Router Cache and Full Route Cache**: > **Difference between the Router Cache and Full Route Cache**:
> >
> The Router Cache temporarily stores the React Server Component Payload in the browser for the duration of a user session, whereas the Full Route Cache persistently stores the React Server Component Payload and HTML on the server across multiple user requests. > The Router Cache temporarily stores the React Server Component Payload in the browser for the duration of a user session, whereas the Full Route Cache persistently stores the React Server Component Payload and HTML on the server across multiple user requests.
> While the Full Route Cache only caches statically rendered routes, the Router Cache applies to both statically and dynamically rendered routes.
> **Related Terms:**
> >
> You may see the Router Cache being referred to as **Client-side Cache** or **Prefetch Cache**. While **Prefetch Cache** refers to the prefetched route segments, **Client-side Cache** refers to the whole Router cache, which includes both visited and prefetched segments. > While the Full Route Cache only caches statically rendered routes, the Router Cache applies to both statically and dynamically rendered routes.
> This cache specifically applies to Next.js and Server Components, and is different to the browser's [bfcache](https://web.dev/bfcache/), though it has a similar result.
### Duration ### Duration
...@@ -387,14 +385,14 @@ When configuring the different caching mechanisms, it's important to understand ...@@ -387,14 +385,14 @@ When configuring the different caching mechanisms, it's important to understand
The following table provides an overview of how different Next.js APIs affect caching: The following table provides an overview of how different Next.js APIs affect caching:
| API | Router Cache | Full Route Cache | Data Cache | React Cache | | API | Router Cache | Full Route Cache | Data Cache | React Cache |
| -------------------------------------------------------------------- | ------------ | --------------------- | --------------------- | ----------- | | ---------------------------------------------------------------------- | ------------ | --------------------- | --------------------- | ----------- |
| [`<Link prefetch>`](#link) | Cache | | | | | [`<Link prefetch>`](#link) | Cache | | | |
| [`router.prefetch`](#routerprefetch) | Cache | | | | | [`router.prefetch`](#routerprefetch) | Cache | | | |
| [`router.refresh`](#routerrefresh) | Revalidate | | | | | [`router.refresh`](#routerrefresh) | Revalidate | | | |
| [`fetch`](#fetch) | | | Cache | Cache | | [`fetch`](#fetch) | | | Cache | Cache |
| [`fetch.options.cache`](#fetch-optionscache) | | | Cache or Opt out | | | [`fetch` `options.cache`](#fetch-optionscache) | | | Cache or Opt out | |
| [`fetch.options.next.revalidate`](#fetch-optionsnextrevalidate) | | Revalidate | Revalidate | | | [`fetch` `options.next.revalidate`](#fetch-optionsnextrevalidate) | | Revalidate | Revalidate | |
| [`fetch.options.next.tags`](#fetch-optionsnexttag-and-revalidatetag) | | Cache | Cache | | | [`fetch` `options.next.tags`](#fetch-optionsnexttag-and-revalidatetag) | | Cache | Cache | |
| [`revalidateTag`](#fetch-optionsnexttag-and-revalidatetag) | | Revalidate | Revalidate | | | [`revalidateTag`](#fetch-optionsnexttag-and-revalidatetag) | | Revalidate | Revalidate | |
| [`revalidatePath`](#revalidatepath) | | Revalidate | Revalidate | | | [`revalidatePath`](#revalidatepath) | | Revalidate | Revalidate | |
| [`const revalidate`](#segment-config-options) | | Revalidate or Opt out | Revalidate or Opt out | | | [`const revalidate`](#segment-config-options) | | Revalidate or Opt out | Revalidate or Opt out | |
...@@ -503,7 +501,7 @@ There are two places you can use `revalidatePath`, depending on what you're tryi ...@@ -503,7 +501,7 @@ There are two places you can use `revalidatePath`, depending on what you're tryi
See the [`revalidatePath` API reference](/docs/app/api-reference/functions/revalidatePath) for more information. See the [`revalidatePath` API reference](/docs/app/api-reference/functions/revalidatePath) for more information.
> **`revalidatePath` vs. `router.refresh`**: > **`revalidatePath`** vs. **`router.refresh`**:
> >
> Calling `router.refresh` will clear the Router cache, and re-render route segments on the server without invalidating the Data Cache or the Full Route Cache. > Calling `router.refresh` will clear the Router cache, and re-render route segments on the server without invalidating the Data Cache or the Full Route 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