Plumbing for cache indicator (#84955)

Author: eps1lon

packages/next/src/build/templates/app-page.ts

@@ -503,6 +503,7 @@ export async function handler(
           subresourceIntegrityManifest,
           serverActionsManifest,
           clientReferenceManifest,
+          setCacheStatus: routerServerContext?.setCacheStatus,
           setIsrStatus: routerServerContext?.setIsrStatus,
           setReactDebugChannel: routerServerContext?.setReactDebugChannel,
 

packages/next/src/client/app-next-dev.ts

@@ -15,6 +15,7 @@ appBootstrap((assetPrefix) => {
   try {
     hydrate(instrumentationHooks, assetPrefix)
   } finally {
-    renderAppDevOverlay(getOwnerStack, isRecoverableError)
+    const enableCacheIndicator = process.env.__NEXT_CACHE_COMPONENTS
+    renderAppDevOverlay(getOwnerStack, isRecoverableError, enableCacheIndicator)
   }
 })

packages/next/src/client/app-next-turbopack.ts

@@ -13,11 +13,16 @@ appBootstrap((assetPrefix) => {
     hydrate(instrumentationHooks, assetPrefix)
   } finally {
     if (process.env.NODE_ENV !== 'production') {
+      const enableCacheIndicator = process.env.__NEXT_CACHE_COMPONENTS
       const { getOwnerStack } =
         require('../next-devtools/userspace/app/errors/stitched-error') as typeof import('../next-devtools/userspace/app/errors/stitched-error')
       const { renderAppDevOverlay } =
         require('next/dist/compiled/next-devtools') as typeof import('next/dist/compiled/next-devtools')
-      renderAppDevOverlay(getOwnerStack, isRecoverableError)
+      renderAppDevOverlay(
+        getOwnerStack,
+        isRecoverableError,
+        enableCacheIndicator
+      )
     }
   }
 })

packages/next/src/client/dev/hot-reloader/app/hot-reloader-app.tsx

@@ -500,6 +500,10 @@ export function processMessage(
       sendMessage(JSON.stringify(response))
       return
     }
+    case HMR_MESSAGE_SENT_TO_BROWSER.CACHE_INDICATOR: {
+      dispatcher.onCacheIndicator(message.state)
+      return
+    }
     case HMR_MESSAGE_SENT_TO_BROWSER.MIDDLEWARE_CHANGES:
     case HMR_MESSAGE_SENT_TO_BROWSER.CLIENT_CHANGES:
     case HMR_MESSAGE_SENT_TO_BROWSER.SERVER_ONLY_CHANGES:

packages/next/src/client/dev/hot-reloader/pages/hot-reloader-pages.ts

@@ -392,6 +392,7 @@ function processMessage(message: HmrMessageSentToBrowser) {
     case HMR_MESSAGE_SENT_TO_BROWSER.DEVTOOLS_CONFIG:
       dispatcher.onDevToolsConfig(message.data)
       break
+    case HMR_MESSAGE_SENT_TO_BROWSER.CACHE_INDICATOR:
     case HMR_MESSAGE_SENT_TO_BROWSER.REACT_DEBUG_CHUNK:
       // Only relevant for app router.
       break

packages/next/src/client/page-bootstrap.ts

@@ -123,6 +123,7 @@ export function pageBootstrap(assetPrefix: string) {
         case HMR_MESSAGE_SENT_TO_BROWSER.REACT_DEBUG_CHUNK:
         case HMR_MESSAGE_SENT_TO_BROWSER.REQUEST_CURRENT_ERROR_STATE:
         case HMR_MESSAGE_SENT_TO_BROWSER.REQUEST_PAGE_METADATA:
+        case HMR_MESSAGE_SENT_TO_BROWSER.CACHE_INDICATOR:
           // Most of these action types are handled in
           // src/client/dev/hot-reloader/pages/hot-reloader-pages.ts and
           // src/client/dev/hot-reloader/app/hot-reloader-app.tsx

packages/next/src/next-devtools/dev-overlay.browser.tsx

@@ -21,6 +21,7 @@ import {
   ACTION_DEVTOOLS_CONFIG,
   type OverlayState,
   type DispatcherEvent,
+  ACTION_CACHE_INDICATOR,
 } from './dev-overlay/shared'
 
 import {
@@ -33,6 +34,7 @@ import {
   type ActionDispatch,
 } from 'react'
 import { createRoot } from 'react-dom/client'
+import type { CacheIndicatorState } from './dev-overlay/cache-indicator'
 import { FontStyles } from './dev-overlay/font/font-styles'
 import type { HydrationErrorState } from './shared/hydration-error'
 import type { DebugInfo } from './shared/types'
@@ -55,6 +57,7 @@ export interface Dispatcher {
   onDebugInfo(debugInfo: DebugInfo): void
   onBeforeRefresh(): void
   onRefresh(): void
+  onCacheIndicator(status: CacheIndicatorState): void
   onStaticIndicator(status: 'pending' | 'static' | 'dynamic' | 'disabled'): void
   onDevIndicator(devIndicator: DevIndicatorServerState): void
   onDevToolsConfig(config: DevToolsConfig): void
@@ -147,6 +150,11 @@ export const dispatcher: Dispatcher = {
       dispatch({ type: ACTION_VERSION_INFO, versionInfo })
     }
   ),
+  onCacheIndicator: createQueuable(
+    (dispatch: Dispatch, status: CacheIndicatorState) => {
+      dispatch({ type: ACTION_CACHE_INDICATOR, cacheIndicator: status })
+    }
+  ),
   onStaticIndicator: createQueuable(
     (
       dispatch: Dispatch,
@@ -230,12 +238,14 @@ function replayQueuedEvents(dispatch: NonNullable<typeof maybeDispatch>) {
 }
 
 function DevOverlayRoot({
+  enableCacheIndicator,
   getOwnerStack,
   getSquashedHydrationErrorDetails,
   isRecoverableError,
   routerType,
   shadowRoot,
 }: {
+  enableCacheIndicator: boolean
   getOwnerStack: (error: Error) => string | null | undefined
   getSquashedHydrationErrorDetails: (error: Error) => HydrationErrorState | null
   isRecoverableError: (error: Error) => boolean
@@ -245,7 +255,8 @@ function DevOverlayRoot({
   const [state, dispatch] = useErrorOverlayReducer(
     routerType,
     getOwnerStack,
-    isRecoverableError
+    isRecoverableError,
+    enableCacheIndicator
   )
 
   useEffect(() => {
@@ -319,7 +330,8 @@ function getSquashedHydrationErrorDetailsApp() {
 
 export function renderAppDevOverlay(
   getOwnerStack: (error: Error) => string | null | undefined,
-  isRecoverableError: (error: Error) => boolean
+  isRecoverableError: (error: Error) => boolean,
+  enableCacheIndicator: boolean
 ): void {
   if (isPagesMounted) {
     // Switching between App and Pages Router is always a hard navigation
@@ -361,6 +373,7 @@ export function renderAppDevOverlay(
       // At least it won't unmount any user code if it errors.
       root.render(
         <DevOverlayRoot
+          enableCacheIndicator={enableCacheIndicator}
           getOwnerStack={getOwnerStack}
           getSquashedHydrationErrorDetails={getSquashedHydrationErrorDetailsApp}
           isRecoverableError={isRecoverableError}
@@ -426,6 +439,8 @@ export function renderPagesDevOverlay(
       // At least it won't unmount any user code if it errors.
       root.render(
         <DevOverlayRoot
+          // Pages Router does not support Cache Components
+          enableCacheIndicator={false}
           getOwnerStack={getOwnerStack}
           getSquashedHydrationErrorDetails={getSquashedHydrationErrorDetails}
           isRecoverableError={isRecoverableError}

packages/next/src/next-devtools/dev-overlay/cache-indicator.tsx

@@ -0,0 +1,2 @@
+export type ServerCacheStatus = 'filling' | 'filled'
+export type CacheIndicatorState = 'disabled' | 'ready' | ServerCacheStatus

packages/next/src/next-devtools/dev-overlay/components/devtools-indicator/devtools-indicator.tsx

@@ -31,6 +31,10 @@ export function DevToolsIndicator() {
     <Toast
       id="devtools-indicator"
       data-nextjs-toast
+      // TODO: Remove once we have actual UI for this.
+      data-nextjs-cache-indicator={
+        state.cacheIndicator === 'disabled' ? undefined : state.cacheIndicator
+      }
       style={
         {
           '--animate-out-duration-ms': `${MENU_DURATION_MS}ms`,

packages/next/src/next-devtools/dev-overlay/shared.ts

@@ -6,6 +6,7 @@ import type { DebugInfo } from '../shared/types'
 import type { DevIndicatorServerState } from '../../server/dev/dev-indicator-server-state'
 import { parseStack } from '../../server/lib/parse-stack'
 import { isConsoleError } from '../shared/console-error'
+import type { CacheIndicatorState } from './cache-indicator'
 
 export type DevToolsConfig = {
   theme?: 'light' | 'dark' | 'system'
@@ -49,6 +50,7 @@ export interface OverlayState {
   readonly notFound: boolean
   readonly buildingIndicator: boolean
   readonly renderingIndicator: boolean
+  readonly cacheIndicator: CacheIndicatorState
   readonly staticIndicator: 'pending' | 'static' | 'dynamic' | 'disabled'
   readonly showIndicator: boolean
   readonly disableDevIndicator: boolean
@@ -72,6 +74,7 @@ export interface OverlayState {
 type DevtoolsPanelName = string
 export type OverlayDispatch = React.Dispatch<DispatcherEvent>
 
+export const ACTION_CACHE_INDICATOR = 'cache-indicator'
 export const ACTION_STATIC_INDICATOR = 'static-indicator'
 export const ACTION_BUILD_OK = 'build-ok'
 export const ACTION_BUILD_ERROR = 'build-error'
@@ -110,6 +113,11 @@ export const STORE_KEY_SHARED_PANEL_LOCATION =
 export const ACTION_DEVTOOL_UPDATE_ROUTE_STATE =
   'segment-explorer-update-route-state'
 
+interface CacheIndicatorAction {
+  type: typeof ACTION_CACHE_INDICATOR
+  cacheIndicator: CacheIndicatorState
+}
+
 interface StaticIndicatorAction {
   type: typeof ACTION_STATIC_INDICATOR
   staticIndicator: 'pending' | 'static' | 'dynamic' | 'disabled'
@@ -216,6 +224,7 @@ export type DispatcherEvent =
   | UnhandledErrorAction
   | UnhandledRejectionAction
   | VersionInfoAction
+  | CacheIndicatorAction
   | StaticIndicatorAction
   | DebugInfoAction
   | DevIndicatorAction
@@ -263,6 +272,7 @@ export const INITIAL_OVERLAY_STATE: Omit<
   errors: [],
   notFound: false,
   renderingIndicator: false,
+  cacheIndicator: 'disabled',
   staticIndicator: 'disabled',
   /* 
     This is set to `true` when we can reliably know
@@ -287,7 +297,8 @@ export const INITIAL_OVERLAY_STATE: Omit<
 }
 
 function getInitialState(
-  routerType: 'pages' | 'app'
+  routerType: 'pages' | 'app',
+  enableCacheIndicator: boolean
 ): OverlayState & { routerType: 'pages' | 'app' } {
   return {
     ...INITIAL_OVERLAY_STATE,
@@ -296,13 +307,15 @@ function getInitialState(
     // TODO: Should be the same default as App Router once we surface console.error in Pages Router.
     isErrorOverlayOpen: routerType === 'pages',
     routerType,
+    cacheIndicator: enableCacheIndicator ? 'ready' : 'disabled',
   }
 }
 
 export function useErrorOverlayReducer(
   routerType: 'pages' | 'app',
   getOwnerStack: (error: Error) => string | null | undefined,
-  isRecoverableError: (error: Error) => boolean
+  isRecoverableError: (error: Error) => boolean,
+  enableCacheIndicator: boolean
 ) {
   function pushErrorFilterDuplicates(
     events: readonly SupportedErrorEvent[],
@@ -349,6 +362,9 @@ export function useErrorOverlayReducer(
         case ACTION_DEBUG_INFO: {
           return { ...state, debugInfo: action.debugInfo }
         }
+        case ACTION_CACHE_INDICATOR: {
+          return { ...state, cacheIndicator: action.cacheIndicator }
+        }
         case ACTION_STATIC_INDICATOR: {
           return { ...state, staticIndicator: action.staticIndicator }
         }
@@ -496,6 +512,6 @@ export function useErrorOverlayReducer(
         }
       }
     },
-    getInitialState(routerType)
+    getInitialState(routerType, enableCacheIndicator)
   )
 }