docs: clarify caching (#69391)

When merging the RC docs into the stable docs, we need to revert changes that apply to core behaviors that have not yet landed on a stable version.
vercel · Aug 28, 2024 · cfab473 · cfab473
1 parent 5b3365e
commit cfab473
Show file tree

Hide file tree

Showing 2 changed files with 35 additions and 60 deletions.
diff --git a/docs/02-app/01-building-your-application/04-caching/index.mdx b/docs/02-app/01-building-your-application/04-caching/index.mdx
@@ -6,7 +6,7 @@ description: An overview of caching mechanisms in Next.js.
 
 Next.js improves your application's performance and reduces costs by caching rendering work and data requests. This page provides an in-depth look at Next.js caching mechanisms, the APIs you can use to configure them, and how they interact with each other.
 
-> **Good to know**: This page helps you understand how Next.js works under the hood but is **not** essential knowledge to be productive with Next.js. Most of Next.js' caching heuristics are determined by your API usage and have defaults for the best performance with zero or minimal configuration.
+> **Good to know**: This page helps you understand how Next.js works under the hood but is **not** essential knowledge to be productive with Next.js. Most of Next.js' caching heuristics are determined by your API usage and have defaults for the best performance with zero or minimal configuration. If you instead want to jump to examples, [start here](/docs/app/building-your-application/data-fetching/fetching).
 
 ## Overview
 
@@ -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 not **cached**. You can use the [`cache`](#fetch-optionscache) and [`next.revalidate`](#fetch-optionsnextrevalidate) options of `fetch` to configure the caching behavior.
+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**
 
@@ -145,8 +145,6 @@ By default, data requests that use `fetch` are not **cached**. You can use the [
 > **Differences between the Data Cache and Request Memoization**
 >
 > While both caching mechanisms help improve performance by re-using cached data, the Data Cache is persistent across incoming requests and deployments, whereas memoization only lasts the lifetime of a request.
->
-> With memoization, we reduce the number of **duplicate** requests in the same render pass that have to cross the network boundary from the rendering server to the Data Cache server (e.g. a CDN or Edge Network) or data source (e.g. a database or CMS). With the Data Cache, we reduce the number of requests made to our origin data source.
 
 ### Duration
 
@@ -210,13 +208,11 @@ Data can be revalidated on-demand by path ([`revalidatePath`](#revalidatepath))
 
 ### Opting out
 
-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.
-
-> **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.
+If you do _not_ want to cache the response from `fetch`, you can do the following:
 
-> **Vercel Data Cache**
->
-> If your Next.js application is deployed to Vercel, we recommend reading the [Vercel Data Cache](https://vercel.com/docs/infrastructure/data-cache) documentation for a better understanding of Vercel specific features.
+```js
+let data = await fetch('https://api.vercel.app/blog', { cache: 'no-store' })
+```
 
 ## Full Route Cache
 
@@ -419,14 +415,13 @@ See the [`useRouter` hook](/docs/app/api-reference/functions/use-router) API ref
 
 ### `fetch`
 
-Data returned from `fetch` is **not** automatically cached in the Data Cache.
+Data returned from `fetch` is automatically cached in the Data Cache.
 
-```jsx
-// Cached by default. `no-store` is the default option and can be omitted.
-fetch(`https://...`, { cache: 'no-store' })
-```
+If you do _not_ want to cache the response from `fetch`, you can do the following:
 
-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.
+```js
+let data = await fetch('https://api.vercel.app/blog', { cache: 'no-store' })
+```
 
 See the [`fetch` API Reference](/docs/app/api-reference/functions/fetch) for more options.
 

diff --git a/docs/02-app/02-api-reference/04-functions/fetch.mdx b/docs/02-app/02-api-reference/04-functions/fetch.mdx
@@ -3,51 +3,37 @@ title: fetch
 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.
+Next.js extends the [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 [Data Cache](/docs/app/building-your-application/caching#data-cache).
 
 You can call `fetch` with `async` and `await` directly within Server Components.
 
 ```tsx filename="app/page.tsx" switcher
 export default async function Page() {
-  // This request should be cached until manually invalidated.
-  // Similar to `getStaticProps`.
-  // `force-cache` is the default and can be omitted.
-  const staticData = await fetch(`https://...`, { cache: 'force-cache' })
-
-  // This request should be refetched on every request.
-  // Similar to `getServerSideProps`.
-  const dynamicData = await fetch(`https://...`, { cache: 'no-store' })
-
-  // This request should be cached with a lifetime of 10 seconds.
-  // Similar to `getStaticProps` with the `revalidate` option.
-  const revalidatedData = await fetch(`https://...`, {
-    next: { revalidate: 10 },
-  })
-
-  return <div>...</div>
+  let data = await fetch('https://api.vercel.app/blog')
+  let posts = await data.json()
+  return (
+    <ul>
+      {posts.map((post) => (
+        <li key={post.id}>{post.title}</li>
+      ))}
+    </ul>
+  )
 }
 ```
 
 ```jsx filename="app/page.js" switcher
 export default async function Page() {
-  // This request should be cached until manually invalidated.
-  // Similar to `getStaticProps`.
-  // `force-cache` is the default and can be omitted.
-  const staticData = await fetch(`https://...`, { cache: 'force-cache' })
-
-  // This request should be refetched on every request.
-  // Similar to `getServerSideProps`.
-  const dynamicData = await fetch(`https://...`, { cache: 'no-store' })
-
-  // This request should be cached with a lifetime of 10 seconds.
-  // Similar to `getStaticProps` with the `revalidate` option.
-  const revalidatedData = await fetch(`https://...`, {
-    next: { revalidate: 10 },
-  })
-
-  return <div>...</div>
+  let data = await fetch('https://api.vercel.app/blog')
+  let posts = await data.json()
+  return (
+    <ul>
+      {posts.map((post) => (
+        <li key={post.id}>{post.title}</li>
+      ))}
+    </ul>
+  )
 }
 ```
 
@@ -63,15 +49,10 @@ Configure how the request should interact with Next.js [Data Cache](/docs/app/bu
 fetch(`https://...`, { cache: 'force-cache' | 'no-store' })
 ```
 
-- **`no-store`** (default): Next.js fetches the resource from the remote server on every request without looking in the cache, and it will not update the cache with the downloaded resource.
-- **`force-cache`**: Next.js looks for a matching request in its Data Cache.
+- **`force-cache`** (default): Next.js looks for a matching request in its Data Cache.
   - If there is a match and it is fresh, it will be returned from the cache.
   - If there is no match or a stale match, Next.js will fetch the resource from the remote server and update the cache with the downloaded resource.
-
-> **Good to know**:
->
-> - In version 15, the default cache option was changed from `'force-cache'` to `'no-store'`. If you're using an older version of Next.js, the default cache option is `'force-cache'`.
-> - The `no-cache` option behaves the same way as `no-store` in Next.js.
+- **`no-store`**: Next.js fetches the resource from the remote server on every request without looking in the cache, and it will not update the cache with the downloaded resource.
 
 ### `options.next.revalidate`
 
@@ -112,7 +93,6 @@ See the [`serverComponentsHmrCache`](/docs/app/api-reference/next-config-js/serv
 
 ## Version History
 
-| Version   | Changes                                                                 |
-| --------- | ----------------------------------------------------------------------- |
-| `v15.0.0` | Default `cache` option was changed from `'force-cache'` to `'no-store'` |
-| `v13.0.0` | `fetch` introduced.                                                     |
+| Version   | Changes             |
+| --------- | ------------------- |
+| `v13.0.0` | `fetch` introduced. |