[Cache Components] Allow hiding logs after abort (#84579)

When Next.js prerenders with Cache Components enabled it will abort
prerenders before they have completed. It is common for user code to log
in a catch block and with this new prerendering behavior these logs will
trigger frequently for cases where the rejection only happened because
we are abandoning the work. This is analagous to treating a fetch
rejection as an error even when you pass an abortSignal into the fetch
and then abort it.

Currently when logs occur after an aborted prerender we dim the log
output to signify that the log line is not particuarly important. This
is useful and for folks who want to see everything output by their
program this is potentially the best behavior. However many log
collectors don't support colors and have no way of contextualizing the
dimmed log which can lead to them appearing to be more significant than
they are.

To combat this we expose a new experimental flag that allows you to
completely disable logs after aborting. This means the log lines you see
are much higher signal.

The implementation is somewhat complex because we install the
environment extensions as early as possible before any user code can run
but we can't install the hiding behavior until we have a config in
scope. I've added the hiding installation to next-server and the worker
exportPages entrypoints. I believe this is sufficient to cover all
contexts in which we will prerender.

Author: gnoff

packages/next/errors.json

@@ -871,5 +871,6 @@
   "870": "refresh can only be called from within a Server Action. See more info here: https://nextjs.org/docs/app/api-reference/functions/refresh",
   "871": "Image with src \"%s\" is using a query string which is not configured in images.localPatterns.\\nRead more: https://nextjs.org/docs/messages/next-image-unconfigured-localpatterns",
   "872": "updateTag can only be called from within a Server Action. To invalidate cache tags in Route Handlers or other contexts, use revalidateTag instead. See more info here: https://nextjs.org/docs/app/api-reference/functions/updateTag",
-  "873": "Invalid profile provided \"%s\" must be configured under cacheLife in next.config or be \"max\""
+  "873": "Invalid profile provided \"%s\" must be configured under cacheLife in next.config or be \"max\"",
+  "874": "Expected not to install Node.js global behaviors in the edge runtime."
 }

packages/next/src/export/worker.ts

@@ -50,6 +50,7 @@ import type { PagesRenderContext, PagesSharedContext } from '../server/render'
 import type { AppSharedContext } from '../server/app-render/app-render'
 import { MultiFileWriter } from '../lib/multi-file-writer'
 import { createRenderResumeDataCache } from '../server/resume-data-cache/resume-data-cache'
+import { installGlobalBehaviors } from '../server/node-environment-extensions/global-behaviors'
 ;(globalThis as any).__NEXT_DATA__ = {
   nextExport: true,
 }
@@ -336,6 +337,8 @@ export async function exportPages(
     renderResumeDataCachesByPage = {},
   } = input
 
+  installGlobalBehaviors(nextConfig)
+
   if (nextConfig.experimental.enablePrerenderSourceMaps) {
     try {
       // Same as `next dev`

packages/next/src/server/config-schema.ts

@@ -346,6 +346,7 @@ export const experimentalSchema = {
     ])
     .optional(),
   lockDistDir: z.boolean().optional(),
+  hideLogsAfterAbort: z.boolean().optional(),
 }
 
 export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>

packages/next/src/server/config-shared.ts

@@ -817,6 +817,14 @@ export interface ExperimentalConfig {
    * @default true
    */
   lockDistDir?: boolean
+
+  /**
+   * Hide logs that occur after a render has already aborted.
+   * This can help reduce noise in the console when dealing with aborted renders.
+   *
+   * @default false
+   */
+  hideLogsAfterAbort?: boolean
 }
 
 export type ExportPathMap = {
@@ -1499,6 +1507,7 @@ export const defaultConfig = Object.freeze({
     lockDistDir: true,
     isolatedDevBuild: true,
     middlewareClientMaxBodySize: 10_485_760, // 10MB
+    hideLogsAfterAbort: false,
   },
   htmlLimitedBots: undefined,
   bundlePagesRouterDependencies: false,

packages/next/src/server/next-server.ts

@@ -123,6 +123,7 @@ import {
   RouterServerContextSymbol,
   routerServerGlobal,
 } from './lib/router-utils/router-server-context'
+import { installGlobalBehaviors } from './node-environment-extensions/global-behaviors'
 
 export * from './base-server'
 
@@ -273,6 +274,8 @@ export default class NextNodeServer extends BaseServer<
     // Initialize super class
     super(options)
 
+    installGlobalBehaviors(this.nextConfig)
+
     const isDev = options.dev ?? false
     this.isDev = isDev
     this.sriEnabled = Boolean(options.conf.experimental?.sri?.algorithm)

packages/next/src/server/node-environment-extensions/console-dim.external.tsx

@@ -11,6 +11,17 @@ export function registerGetCacheSignal(getSignal: GetCacheSignal): void {
   cacheSignals.push(getSignal)
 }
 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- we may use later and want parity with the HIDDEN_STYLE value
+const DIMMED_STYLE = 'dimmed'
+const HIDDEN_STYLE = 'hidden'
+
+type LogStyle = typeof DIMMED_STYLE | typeof HIDDEN_STYLE
+
+let currentAbortedLogsStyle: LogStyle = 'dimmed'
+export function setAbortedLogsStyle(style: LogStyle) {
+  currentAbortedLogsStyle = style
+}
+
 type InterceptableConsoleMethod =
   | 'error'
   | 'assert'
@@ -175,75 +186,89 @@ function patchConsoleMethod(methodName: InterceptableConsoleMethod): void {
     const wrapperMethod = function (this: typeof console, ...args: any[]) {
       const consoleStore = consoleAsyncStorage.getStore()
 
-      if (consoleStore?.dim === true) {
-        return applyWithDimming.call(
-          this,
-          consoleStore,
-          originalMethod,
-          methodName,
-          args
-        )
-      } else {
-        // First we see if there is a cache signal for our current scope. If we're in a client render it'll
-        // come from the client React cacheSignal implementation. If we are in a server render it'll come from
-        // the server React cacheSignal implementation. Any particular console call will be in one, the other, or neither
-        // scope and these signals return null if you are out of scope so this can be called from a single global patch
-        // and still work properly.
-        for (let i = 0; i < cacheSignals.length; i++) {
-          const signal = cacheSignals[i]() // try to get a signal from registered functions
-          if (signal) {
-            // We are in a React Server render and can consult the React cache signal to determine if logs
-            // are now dimmable.
-            if (signal.aborted) {
-              return applyWithDimming.call(
-                this,
-                consoleStore,
-                originalMethod,
-                methodName,
-                args
-              )
-            } else {
-              return originalMethod.apply(this, args)
+      // First we see if there is a cache signal for our current scope. If we're in a client render it'll
+      // come from the client React cacheSignal implementation. If we are in a server render it'll come from
+      // the server React cacheSignal implementation. Any particular console call will be in one, the other, or neither
+      // scope and these signals return null if you are out of scope so this can be called from a single global patch
+      // and still work properly.
+      for (let i = 0; i < cacheSignals.length; i++) {
+        const signal = cacheSignals[i]() // try to get a signal from registered functions
+        if (signal) {
+          // We are in a React Server render and can consult the React cache signal to determine if logs
+          // are now dimmable.
+          if (signal.aborted) {
+            if (currentAbortedLogsStyle === HIDDEN_STYLE) {
+              return
             }
+            return applyWithDimming.call(
+              this,
+              consoleStore,
+              originalMethod,
+              methodName,
+              args
+            )
+          } else if (consoleStore?.dim === true) {
+            return applyWithDimming.call(
+              this,
+              consoleStore,
+              originalMethod,
+              methodName,
+              args
+            )
+          } else {
+            return originalMethod.apply(this, args)
           }
         }
-        // We need to fall back to checking the work unit store for two reasons.
-        // 1. Client React does not yet implement cacheSignal (it always returns null)
-        // 2. route.ts files aren't rendered with React but do have prerender semantics
-        // TODO in the future we should be able to remove this once there is a runnable cache
-        // scope independent of actual React rendering.
-        const workUnitStore = workUnitAsyncStorage.getStore()
-        switch (workUnitStore?.type) {
-          case 'prerender':
-          case 'prerender-runtime':
-          // These can be hit in a route handler. In the future we can use potential React.createCache API
-          // to create a cache scope for arbitrary computation and can move over to cacheSignal exclusively.
-          // fallthrough
-          case 'prerender-client':
-            // This is a react-dom/server render and won't have a cacheSignal until React adds this for the client world.
-            const renderSignal = workUnitStore.renderSignal
-            if (renderSignal.aborted) {
-              return applyWithDimming.call(
-                this,
-                consoleStore,
-                originalMethod,
-                methodName,
-                args
-              )
-            } else {
-              return originalMethod.apply(this, args)
+      }
+
+      // We need to fall back to checking the work unit store for two reasons.
+      // 1. Client React does not yet implement cacheSignal (it always returns null)
+      // 2. route.ts files aren't rendered with React but do have prerender semantics
+      // TODO in the future we should be able to remove this once there is a runnable cache
+      // scope independent of actual React rendering.
+      const workUnitStore = workUnitAsyncStorage.getStore()
+      switch (workUnitStore?.type) {
+        case 'prerender':
+        case 'prerender-runtime':
+        // These can be hit in a route handler. In the future we can use potential React.createCache API
+        // to create a cache scope for arbitrary computation and can move over to cacheSignal exclusively.
+        // fallthrough
+        case 'prerender-client':
+          // This is a react-dom/server render and won't have a cacheSignal until React adds this for the client world.
+          const renderSignal = workUnitStore.renderSignal
+          if (renderSignal.aborted) {
+            if (currentAbortedLogsStyle === HIDDEN_STYLE) {
+              return
             }
-          case 'prerender-legacy':
-          case 'prerender-ppr':
-          case 'cache':
-          case 'unstable-cache':
-          case 'private-cache':
-          case 'request':
-          case undefined:
+            return applyWithDimming.call(
+              this,
+              consoleStore,
+              originalMethod,
+              methodName,
+              args
+            )
+          }
+        // intentional fallthrough
+        case 'prerender-legacy':
+        case 'prerender-ppr':
+        case 'cache':
+        case 'unstable-cache':
+        case 'private-cache':
+        case 'request':
+        case undefined:
+          if (consoleStore?.dim === true) {
+            return applyWithDimming.call(
+              this,
+              consoleStore,
+              originalMethod,
+              methodName,
+              args
+            )
+          } else {
             return originalMethod.apply(this, args)
-          default:
-            workUnitStore satisfies never
-        }
+          }
+        default:
+          workUnitStore satisfies never
       }
     }
     if (originalName) {

packages/next/src/server/node-environment-extensions/global-behaviors.tsx

@@ -0,0 +1,23 @@
+/**
+ * Unlike most files in the node-environment-extensions folder this one is not
+ * an extension itself but it exposes a function to install config based global
+ * behaviors that should be loaded whenever a Node Server or Node Worker are created.
+ */
+import type { NextConfigComplete } from '../config-shared'
+import { InvariantError } from '../../shared/lib/invariant-error'
+
+import { setAbortedLogsStyle } from './console-dim.external'
+
+export function installGlobalBehaviors(config: NextConfigComplete) {
+  if (process.env.NEXT_RUNTIME === 'edge') {
+    throw new InvariantError(
+      'Expected not to install Node.js global behaviors in the edge runtime.'
+    )
+  }
+
+  if (config.experimental?.hideLogsAfterAbort === true) {
+    setAbortedLogsStyle('hidden')
+  } else {
+    setAbortedLogsStyle('dimmed')
+  }
+}