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

Docs: Update `fetch` information in caching docs (#67279)

Updates data cache docs to reflect `fetch` behavior in Next.js 15 RC. 

Closes: https://github.com/vercel/next.js/issues/67238

---------
Co-authored-by: 's avatarSam Ko <sam@vercel.com>
parent fc87f8ee
......@@ -124,7 +124,7 @@ Next.js has a built-in Data Cache that **persists** the result of data fetches a
> **Good to know**: In the browser, the `cache` option of `fetch` indicates how a request will interact with the browser's HTTP cache, in Next.js, the `cache` option indicates how a server-side request will interact with the server's 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 not **cached**. You can use the [`cache`](#fetch-optionscache) and [`next.revalidate`](#fetch-optionsnextrevalidate) options of `fetch` to configure the caching behavior.
**How the Data Cache Works**
......@@ -136,10 +136,10 @@ By default, data requests that use `fetch` are **cached**. You can use the [`cac
height="661"
/>
- The first time a `fetch` request is called during rendering, Next.js checks the Data Cache for a cached response.
- The first time a `fetch` request with the `'force-cache'` option is called during rendering, Next.js checks the Data Cache for a cached response.
- If a cached response is found, it's returned immediately and [memoized](#request-memoization).
- If a cached response is not found, the request is made to the data source, the result is stored in the Data Cache, and memoized.
- For uncached data (e.g. `{ cache: 'no-store' }`), the result is always fetched from the data source, and memoized.
- For uncached data (e.g. no `cache` option defined or using `{ cache: 'no-store' }`), the result is always fetched from the data source, and memoized.
- Whether the data is cached or uncached, the requests are always memoized to avoid making duplicate requests for the same data during a React render pass.
> **Differences between the Data Cache and Request Memoization**
......@@ -210,21 +210,9 @@ Data can be revalidated on-demand by path ([`revalidatePath`](#revalidatepath))
### Opting out
For individual data fetches, you can opt out of caching by setting the [`cache`](#fetch-optionscache) option to `no-store`. This means data will be fetched whenever `fetch` is called.
Since `fetch` requests are not cached by default, you don't need to opt out of caching. This means data will be fetched from your data source whenever `fetch` is called.
```jsx
// Opt out of caching for an individual `fetch` request
fetch(`https://...`, { cache: 'no-store' })
```
Alternatively, you can also use the [Route Segment Config options](#segment-config-options) to opt out of caching for a specific route segment. This will affect all data requests in the route segment, including third-party libraries.
```jsx
// Opt out of caching for all data requests in the route segment
export const dynamic = 'force-dynamic'
```
> **Note**: Data Cache is currently only available in pages/routes, not middleware. Any fetches done inside of your middleware will be uncached by default.
> **Note**: Data Cache is currently only available in Layout, Pages, and Route Handlers, not Middleware. Any fetches done inside of your middleware will not be cached by default.
> **Vercel Data Cache**
>
......@@ -431,26 +419,26 @@ See the [`useRouter` hook](/docs/app/api-reference/functions/use-router) API ref
### `fetch`
Data returned from `fetch` is automatically cached in the Data Cache.
Data returned from `fetch` is **not** automatically cached in the Data Cache.
```jsx
// Cached by default. `force-cache` is the default option and can be omitted.
fetch(`https://...`, { cache: 'force-cache' })
// Cached by default. `no-store` is the default option and can be omitted.
fetch(`https://...`, { cache: 'no-store' })
```
Since the render output depends on data, using `cache: 'no-store'` will also skip the Full Route Cache for the route where the `fetch` request is used. That is, the route will be dynamically rendered on every request, but you can still have other cached data requests in the same route.
See the [`fetch` API Reference](/docs/app/api-reference/functions/fetch) for more options.
### `fetch options.cache`
You can opt out individual `fetch` requests of data caching by setting the `cache` option to `no-store`:
You can opt individual `fetch` into caching by setting the `cache` option to `force-cache`:
```jsx
// Opt out of caching
fetch(`https://...`, { cache: 'no-store' })
fetch(`https://...`, { cache: 'force-cache' })
```
Since the render output depends on data, using `cache: 'no-store'` will also skip the Full Route Cache for the route where the `fetch` request is used. That is, the route will be dynamically rendered every request, but you can still have other cached data requests in the same route.
See the [`fetch` API Reference](/docs/app/api-reference/functions/fetch) for more options.
### `fetch options.next.revalidate`
......
......@@ -5,7 +5,7 @@ description: API reference for the extended fetch function.
Next.js extends the native [Web `fetch()` API](https://developer.mozilla.org/docs/Web/API/Fetch_API) to allow each request on the server to set its own persistent caching and revalidation semantics.
In the browser, the `cache` option indicates how a fetch request will interact with the _browser's_ HTTP cache. With this extension, `cache` indicates how a _server-side_ fetch request will interact with the framework's persistent HTTP cache.
In the browser, the `cache` option indicates how a fetch request will interact with the _browser's_ HTTP cache. With this extension, `cache` indicates how a _server-side_ fetch request will interact with the framework's persistent [Data Cache](/docs/app/building-your-application/caching#data-cache).
You can call `fetch` with `async` and `await` directly within Server Components.
......
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