Skip to content

Commit

Permalink
Docs: Update fetch information in caching docs (vercel#67279)
Browse files Browse the repository at this point in the history
Updates data cache docs to reflect `fetch` behavior in Next.js 15 RC. 

Closes: vercel#67238

---------

Co-authored-by: Sam Ko <sam@vercel.com>
  • Loading branch information
delbaoliveira and samcx authored Jun 28, 2024
1 parent fc87f8e commit fbede36
Show file tree
Hide file tree
Showing 2 changed files with 13 additions and 25 deletions.
36 changes: 12 additions & 24 deletions docs/02-app/01-building-your-application/04-caching/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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**

Expand All @@ -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**
Expand Down Expand Up @@ -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**
>
Expand Down Expand Up @@ -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`
Expand Down
2 changes: 1 addition & 1 deletion docs/02-app/02-api-reference/04-functions/fetch.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down

0 comments on commit fbede36

Please sign in to comment.