[Cache Components] When caches are disabled in dev skip the cache warmup

gnoff · gnoff · commit 0d57169b2ccb · 2025-10-18T14:18:51.000-07:00
In Dev, to ensure the component metadata that powers React DevTools accurately reflects the cached, prerendered, or dynamic nature of Server Components, Next.js ensures that any caches encountered during the prerender are warm before streaming.

However when users have chrome devtools open with "disable caches" or when a hard refresh is performed requests are made with a cache header that instructs Next.js to bypass all server caches. In these cases every request will always have empty caches and thus the entire request will block on the time it takes to fill all caches. It isn't reccomended to typically disable cache while developing with Next.js because it is even more aggressive than the cold cache scenario real users would encounter with a production deployment. But there are some reasons why it is legitimate, for instance when you want to force any latent caches in memory to by skipped. When this happens Next.js will now skip cache warming to ensure the render is streamed quickly. We will also warn in the console that the request did not have caches warmed up and Component Metadata in React DevTools won't accurately reflect which components are cacheable and prefetchable.

In the future we will also show this state in the Next.js devtools UI so it is clearer you are operating in this mode without having to read a warning log in the console
diff --git a/errors/cache-bypass-in-dev.mdx b/errors/cache-bypass-in-dev.mdx
@@ -0,0 +1,30 @@
+---
+title: Caches Bypassed in Development Mode
+---
+
+## Disabling Caches in Development Mode
+
+While running Next.js in development mode with `next dev` an initial page load or client navigation was handled with a `cache-control: no-store` header. The most common reason for this is that you have your web browser's DevTools open with "Disable Cache" enabled. Another common reason is you performed a hard refresh (Cmd + Shift + R / Ctrl + Shift + R).
+
+Disabling caches while in development mode affects the debugging experience of Cache Components. Read on to understand more about how Next.js handles caches in development mode and what changes when they are intentionally disabled.
+
+## Understanding Cache handling in Development Mode
+
+In development mode, Next.js ensures that Cache Components render in the right environment to allow for React DevTools to highlight which components are part of the available for prerendering statically before any user request, which are available when prefetching segments at runtime before a navigation occurs, and finally which are dynamic and will only be fetched on user navigation.
+
+This behavior has a small cost when a cold cache is encountered. Rather than streaming immediately Next.js will wait to fill this cache before streaming the response. As you navigate around you App in development mode these caches will fill and most navigations to cached content should feel instant once warm.
+
+However if you instruct Next.js to skip all server caches using something like the "Disable Cache" option in your browser's DevTools, this behavior would be detrimental since every cache will be considered cold on every request leading to blocking navigations. Instead Next.js prints a warning that this particular request is not suitable for debugging Cache Components and then renders fresh results as fast as possible.
+
+## Should you use "Disable Cache"?
+
+Chrome, in particular, defaults all network request to "Disable Cache" when DevTools is open. For Next.js this is not recommended because it is overly aggressive in what is not cached and can provide a false impression of page performance that doesn't represent realistic usage of a web app.
+
+However there are times when disabling a server caches can be useful. For instance if you know some upstream data system has updated but these updates are not connected to your local dev environment through features like `revalidateTag`.
+
+If you must turn on "Disable Cache" to force a refresh we recommend that you disable the option once you've achieved your goal.
+
+## Useful Links
+
+- [`revalidateTag` function](/docs/app/api-reference/functions/revalidateTag)
+- [`"use cache"` directive](/docs/app/api-reference/directives/use-cache)
diff --git a/packages/next/src/server/app-render/app-render.tsx b/packages/next/src/server/app-render/app-render.tsx
@@ -578,7 +578,7 @@ async function generateDynamicFlightRenderResult(
 ): Promise<RenderResult> {
   const {
     clientReferenceManifest,
-    componentMod,
+    componentMod: { renderToReadableStream, createElement },
     htmlRequestId,
     renderOpts,
     requestId,
@@ -606,13 +606,23 @@ async function generateDynamicFlightRenderResult(
   const RSCPayload: RSCPayload & {
     /** Only available during cacheComponents development builds. Used for logging errors. */
     _validation?: Promise<ReactNode>
+    _bypassCachesInDev?: React.ReactNode
   } = await workUnitAsyncStorage.run(
     requestStore,
     generateDynamicRSCPayload,
     ctx,
     options
   )
 
+  if (
+    process.env.NODE_ENV === 'development' &&
+    isBypassingCachesInDev(renderOpts, requestStore)
+  ) {
+    RSCPayload._bypassCachesInDev = createElement(WarnForBypassCachesInDev, {
+      route: workStore.route,
+    })
+  }
+
   const debugChannel = setReactDebugChannel && createDebugChannel()
 
   if (debugChannel) {
@@ -623,7 +633,7 @@ async function generateDynamicFlightRenderResult(
   // which contains the subset React.
   const flightReadableStream = workUnitAsyncStorage.run(
     requestStore,
-    componentMod.renderToReadableStream,
+    renderToReadableStream,
     RSCPayload,
     clientReferenceManifest.clientModules,
     {
@@ -1864,10 +1874,15 @@ async function renderToHTMLOrFlightImpl(
       if (isRuntimePrefetchRequest) {
         return generateRuntimePrefetchResult(req, res, ctx, requestStore)
       } else {
+        const bypassCachesInDev = isBypassingCachesInDev(
+          renderOpts,
+          requestStore
+        )
         if (
           process.env.NODE_ENV === 'development' &&
           process.env.NEXT_RUNTIME !== 'edge' &&
-          cacheComponents
+          cacheComponents &&
+          !bypassCachesInDev
         ) {
           return generateDynamicFlightRenderResultWithCachesInDev(
             req,
@@ -2174,14 +2189,24 @@ async function renderToStream(
   devValidatingFallbackParams: OpaqueFallbackRouteParams | null
 ): Promise<ReadableStream<Uint8Array>> {
   /* eslint-disable @next/internal/no-ambiguous-jsx -- React Client */
-  const { assetPrefix, htmlRequestId, nonce, pagePath, renderOpts, requestId } =
-    ctx
+  const {
+    assetPrefix,
+    htmlRequestId,
+    nonce,
+    pagePath,
+    renderOpts,
+    requestId,
+    workStore,
+  } = ctx
 
   const {
     basePath,
     buildManifest,
     clientReferenceManifest,
-    ComponentMod,
+    ComponentMod: {
+      createElement,
+      renderToReadableStream: serverRenderToReadableStream,
+    },
     crossOrigin,
     dev = false,
     experimental,
@@ -2286,17 +2311,20 @@ async function renderToStream(
 
   try {
     if (
-      // We only want this behavior when running `next dev`
-      dev &&
       // We only want this behavior when we have React's dev builds available
       process.env.NODE_ENV === 'development' &&
+      // We only want this behavior when running `next dev`
+      dev &&
       // Edge routes never prerender so we don't have a Prerender environment for anything in edge runtime
       process.env.NEXT_RUNTIME !== 'edge' &&
       // We only have a Prerender environment for projects opted into cacheComponents
       cacheComponents &&
       // We only do this flow if we can safely recreate the store from scratch
       // (which is not the case for renders after an action)
-      createRequestStore
+      createRequestStore &&
+      // We only do this flow if we're not bypassing caches in dev using
+      // "disable cache" in devtools or a hard refresh (cache-control: "no-store")
+      !isBypassingCachesInDev(renderOpts, requestStore)
     ) {
       type RSCPayloadWithValidation = InitialRSCPayload & {
         /** Only available during cacheComponents development builds. Used for logging errors. */
@@ -2369,14 +2397,25 @@ async function renderToStream(
       )
     } else {
       // This is a dynamic render. We don't do dynamic tracking because we're not prerendering
-      const RSCPayload = await workUnitAsyncStorage.run(
+      const RSCPayload: RSCPayload & {
+        _bypassCachesInDev?: React.ReactNode
+      } = await workUnitAsyncStorage.run(
         requestStore,
         getRSCPayload,
         tree,
         ctx,
         res.statusCode === 404
       )
 
+      if (isBypassingCachesInDev(renderOpts, requestStore)) {
+        // Mark the RSC payload to indicate that caches were bypassed in dev.
+        // This lets the client know not to cache anything based on this render.
+        RSCPayload._bypassCachesInDev = createElement(
+          WarnForBypassCachesInDev,
+          { route: workStore.route }
+        )
+      }
+
       const debugChannel = setReactDebugChannel && createDebugChannel()
 
       if (debugChannel) {
@@ -2395,7 +2434,7 @@ async function renderToStream(
       reactServerResult = new ReactServerResult(
         workUnitAsyncStorage.run(
           requestStore,
-          ComponentMod.renderToReadableStream,
+          serverRenderToReadableStream,
           RSCPayload,
           clientReferenceManifest.clientModules,
           {
@@ -2624,7 +2663,7 @@ async function renderToStream(
 
     const errorServerStream = workUnitAsyncStorage.run(
       requestStore,
-      ComponentMod.renderToReadableStream,
+      serverRenderToReadableStream,
       errorRSCPayload,
       clientReferenceManifest.clientModules,
       {
@@ -5123,3 +5162,21 @@ async function collectSegmentData(
     serverConsumerManifest
   )
 }
+
+function isBypassingCachesInDev(
+  renderOpts: RenderOpts,
+  requestStore: RequestStore
+): boolean {
+  return (
+    process.env.NODE_ENV === 'development' &&
+    !!renderOpts.dev &&
+    requestStore.headers.get('cache-control') === 'no-cache'
+  )
+}
+
+function WarnForBypassCachesInDev({ route }: { route: string }) {
+  console.warn(
+    `Route ${route} is rendering with server caches disabled. For this navigation, Component Metadata in React DevTools will not accurately reflect what is statically prerenderable and runtime prefetchable. See more info here: https://nextjs.org/docs/messages/cache-bypass-in-dev`
+  )
+  return null
+}
diff --git a/test/e2e/app-dir/cache-components-errors/cache-components-dev-cache-bypass.test.ts b/test/e2e/app-dir/cache-components-errors/cache-components-dev-cache-bypass.test.ts
@@ -0,0 +1,117 @@
+import { isNextDev, nextTestSetup } from 'e2e-utils'
+
+describe('Cache Components Errors', () => {
+  const { next, skipped } = nextTestSetup({
+    files: __dirname + '/fixtures/dev-cache-bypass',
+  })
+
+  if (skipped) {
+    return
+  }
+
+  describe('Warning for Bypassing Caches in Dev', () => {
+    if (isNextDev) {
+      it('warns if you render with cache-control: no-cache in dev on initial page load', async () => {
+        const from = next.cliOutput.length
+
+        await next.fetch('/', {
+          headers: { 'cache-control': 'no-cache' },
+        })
+
+        expect(stripGetLines(next.cliOutput.slice(from)))
+          .toMatchInlineSnapshot(`
+         "Route / is rendering with server caches disabled. For this navigation, Component Metadata in React DevTools will not accurately reflect what is statically prerenderable and runtime prefetchable. See more info here: https://nextjs.org/docs/messages/cache-bypass-in-dev
+         "
+        `)
+      })
+
+      it('warns if you render with cache-control: no-cache in dev on client navigation', async () => {
+        const from = next.cliOutput.length
+
+        await next.fetch('/', {
+          headers: { 'cache-control': 'no-cache', RSC: '1' },
+        })
+
+        expect(stripGetLines(next.cliOutput.slice(from)))
+          .toMatchInlineSnapshot(`
+         "Route / is rendering with server caches disabled. For this navigation, Component Metadata in React DevTools will not accurately reflect what is statically prerenderable and runtime prefetchable. See more info here: https://nextjs.org/docs/messages/cache-bypass-in-dev
+         "
+        `)
+      })
+
+      it('does not warn if you render without cache-control: no-cache in dev on initial page load', async () => {
+        const from = next.cliOutput.length
+
+        await next.fetch('/')
+
+        expect(stripGetLines(next.cliOutput.slice(from))).toMatchInlineSnapshot(
+          `""`
+        )
+      })
+
+      it('does not warn if you render without cache-control: no-cache in dev on client navigation', async () => {
+        const from = next.cliOutput.length
+
+        await next.fetch('/', {
+          headers: { RSC: '1' },
+        })
+
+        expect(stripGetLines(next.cliOutput.slice(from))).toMatchInlineSnapshot(
+          `""`
+        )
+      })
+    } else {
+      it('does not warn if you render with cache-control: no-cache in dev on initial page load', async () => {
+        const from = next.cliOutput.length
+
+        await next.fetch('/', {
+          headers: { 'cache-control': 'no-cache' },
+        })
+
+        expect(stripGetLines(next.cliOutput.slice(from))).toMatchInlineSnapshot(
+          `""`
+        )
+      })
+
+      it('does not warn if you render with cache-control: no-cache in dev on client navigation', async () => {
+        const from = next.cliOutput.length
+
+        await next.fetch('/', {
+          headers: { 'cache-control': 'no-cache' },
+        })
+
+        expect(stripGetLines(next.cliOutput.slice(from))).toMatchInlineSnapshot(
+          `""`
+        )
+      })
+
+      it('does not warn if you render without cache-control: no-cache in dev on initial page load in start', async () => {
+        const from = next.cliOutput.length
+
+        await next.fetch('/')
+
+        expect(stripGetLines(next.cliOutput.slice(from))).toMatchInlineSnapshot(
+          `""`
+        )
+      })
+
+      it('does not warn if you render without cache-control: no-cache in dev on client navigation in start', async () => {
+        const from = next.cliOutput.length
+
+        await next.fetch('/', {
+          headers: { RSC: '1' },
+        })
+
+        expect(stripGetLines(next.cliOutput.slice(from))).toMatchInlineSnapshot(
+          `""`
+        )
+      })
+    }
+  })
+})
+
+function stripGetLines(input: string): string {
+  return input
+    .replace(/^\s*GET.*(?:\r?\n|$)/gm, '')
+    .replace(/^\s*[○✓].*(?:\r?\n|$)/gm, '')
+}
diff --git a/test/e2e/app-dir/cache-components-errors/fixtures/dev-cache-bypass/app/layout.tsx b/test/e2e/app-dir/cache-components-errors/fixtures/dev-cache-bypass/app/layout.tsx
@@ -0,0 +1,9 @@
+export default function Root({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body>
+        <main>{children}</main>
+      </body>
+    </html>
+  )
+}
diff --git a/test/e2e/app-dir/cache-components-errors/fixtures/dev-cache-bypass/app/other/page.tsx b/test/e2e/app-dir/cache-components-errors/fixtures/dev-cache-bypass/app/other/page.tsx
@@ -0,0 +1,34 @@
+import { Suspense } from 'react'
+import Link from 'next/link'
+
+export default async function Page() {
+  return (
+    <main>
+      <section>
+        <p>
+          This page has has a slow to fill cache. When not bypassing the dev
+          cache the initial load should be slow while the cache warms up. You
+          won't see the Suspense fallback because the entire response is blocked
+          until the cache warms up. Subsequent loads should be fast because the
+          cache is warm and nothing needs to Suspend When bypassing caches in
+          dev with "disable cache" the request should instantly show a fallback
+          UI and show the final content after the delay.
+        </p>
+      </section>
+      <section>
+        <Suspense fallback={<p>Loading from cache...</p>}>
+          <CachedData />
+        </Suspense>
+      </section>
+      <Link href="/">Go back home</Link>
+    </main>
+  )
+}
+
+async function CachedData() {
+  'use cache'
+
+  await new Promise((r) => setTimeout(r, 2000))
+
+  return <p>{67}</p>
+}
diff --git a/test/e2e/app-dir/cache-components-errors/fixtures/dev-cache-bypass/app/page.tsx b/test/e2e/app-dir/cache-components-errors/fixtures/dev-cache-bypass/app/page.tsx
diff --git a/test/e2e/app-dir/cache-components-errors/fixtures/dev-cache-bypass/next.config.js b/test/e2e/app-dir/cache-components-errors/fixtures/dev-cache-bypass/next.config.js
