Add "nested-update" phase to Profiler API

State updates that are scheduled in a layout effect (useLayoutEffect or componentDidMount / componentDidUpdate) get processed synchronously by React before it yields to the browser to paint. This is done so that components can adjust their layout (e.g. position and size a tooltip) without any visible shifting being seen by users. This type of update is often called a "nested update" or a "cascading update".

Because they delay paint, nested updates are considered "expensive" and should be avoided when possible. For example, effects that do not impact layout (e.g. adding event handlers, logging impressions) can be safely deferred to the passive effect phase by using useEffect instead.

This commit updates the Profiler API to explicitly flag nested updates so they can be identified and avoided when possible.

packages/react-reconciler/src/ReactFiberCommitWork.new.js

@@ -31,6 +31,7 @@ import {
   enableSchedulerTracing,
   enableProfilerTimer,
   enableProfilerCommitHooks,
+  enableProfilerNestedUpdatePhase,
   enableSuspenseServerRenderer,
   enableFundamentalAPI,
   enableSuspenseCallback,
@@ -94,6 +95,7 @@ import {
 import {onCommitUnmount} from './ReactFiberDevToolsHook.new';
 import {resolveDefaultProps} from './ReactFiberLazyComponent.new';
 import {
+  isCurrentUpdateNested,
   getCommitTime,
   recordLayoutEffectDuration,
   startLayoutEffectTimer,
@@ -369,22 +371,24 @@ function commitProfilerPassiveEffect(
         // It does not get reset until the start of the next commit phase.
         const commitTime = getCommitTime();
 
+        let phase = finishedWork.alternate === null ? 'mount' : 'update';
+        if (enableProfilerNestedUpdatePhase) {
+          if (isCurrentUpdateNested()) {
+            phase = 'nested-update';
+          }
+        }
+
         if (typeof onPostCommit === 'function') {
           if (enableSchedulerTracing) {
             onPostCommit(
               id,
-              finishedWork.alternate === null ? 'mount' : 'update',
+              phase,
               passiveEffectDuration,
               commitTime,
               finishedRoot.memoizedInteractions,
             );
           } else {
-            onPostCommit(
-              id,
-              finishedWork.alternate === null ? 'mount' : 'update',
-              passiveEffectDuration,
-              commitTime,
-            );
+            onPostCommit(id, phase, passiveEffectDuration, commitTime);
           }
         }
         break;
@@ -1362,11 +1366,18 @@ function commitLayoutEffectsForProfiler(
     const OnRenderFlag = Update;
     const OnCommitFlag = Callback;
 
+    let phase = current === null ? 'mount' : 'update';
+    if (enableProfilerNestedUpdatePhase) {
+      if (isCurrentUpdateNested()) {
+        phase = 'nested-update';
+      }
+    }
+
     if ((flags & OnRenderFlag) !== NoFlags && typeof onRender === 'function') {
       if (enableSchedulerTracing) {
         onRender(
           finishedWork.memoizedProps.id,
-          current === null ? 'mount' : 'update',
+          phase,
           finishedWork.actualDuration,
           finishedWork.treeBaseDuration,
           finishedWork.actualStartTime,
@@ -1376,7 +1387,7 @@ function commitLayoutEffectsForProfiler(
       } else {
         onRender(
           finishedWork.memoizedProps.id,
-          current === null ? 'mount' : 'update',
+          phase,
           finishedWork.actualDuration,
           finishedWork.treeBaseDuration,
           finishedWork.actualStartTime,
@@ -1393,15 +1404,15 @@ function commitLayoutEffectsForProfiler(
         if (enableSchedulerTracing) {
           onCommit(
             finishedWork.memoizedProps.id,
-            current === null ? 'mount' : 'update',
+            phase,
             effectDuration,
             commitTime,
             finishedRoot.memoizedInteractions,
           );
         } else {
           onCommit(
             finishedWork.memoizedProps.id,
-            current === null ? 'mount' : 'update',
+            phase,
             effectDuration,
             commitTime,
           );

packages/react-reconciler/src/ReactFiberCommitWork.old.js

@@ -30,6 +30,7 @@ import {
   enableSchedulerTracing,
   enableProfilerTimer,
   enableProfilerCommitHooks,
+  enableProfilerNestedUpdatePhase,
   enableSuspenseServerRenderer,
   enableFundamentalAPI,
   enableSuspenseCallback,
@@ -73,6 +74,7 @@ import invariant from 'shared/invariant';
 import {onCommitUnmount} from './ReactFiberDevToolsHook.old';
 import {resolveDefaultProps} from './ReactFiberLazyComponent.old';
 import {
+  isCurrentUpdateNested,
   getCommitTime,
   recordLayoutEffectDuration,
   startLayoutEffectTimer,
@@ -434,22 +436,24 @@ export function commitPassiveEffectDurations(
           // It does not get reset until the start of the next commit phase.
           const commitTime = getCommitTime();
 
+          let phase = finishedWork.alternate === null ? 'mount' : 'update';
+          if (enableProfilerNestedUpdatePhase) {
+            if (isCurrentUpdateNested()) {
+              phase = 'nested-update';
+            }
+          }
+
           if (typeof onPostCommit === 'function') {
             if (enableSchedulerTracing) {
               onPostCommit(
                 id,
-                finishedWork.alternate === null ? 'mount' : 'update',
+                phase,
                 passiveEffectDuration,
                 commitTime,
                 finishedRoot.memoizedInteractions,
               );
             } else {
-              onPostCommit(
-                id,
-                finishedWork.alternate === null ? 'mount' : 'update',
-                passiveEffectDuration,
-                commitTime,
-              );
+              onPostCommit(id, phase, passiveEffectDuration, commitTime);
             }
           }
 
@@ -706,11 +710,18 @@ function commitLifeCycles(
 
         const commitTime = getCommitTime();
 
+        let phase = current === null ? 'mount' : 'update';
+        if (enableProfilerNestedUpdatePhase) {
+          if (isCurrentUpdateNested()) {
+            phase = 'nested-update';
+          }
+        }
+
         if (typeof onRender === 'function') {
           if (enableSchedulerTracing) {
             onRender(
               finishedWork.memoizedProps.id,
-              current === null ? 'mount' : 'update',
+              phase,
               finishedWork.actualDuration,
               finishedWork.treeBaseDuration,
               finishedWork.actualStartTime,
@@ -720,7 +731,7 @@ function commitLifeCycles(
           } else {
             onRender(
               finishedWork.memoizedProps.id,
-              current === null ? 'mount' : 'update',
+              phase,
               finishedWork.actualDuration,
               finishedWork.treeBaseDuration,
               finishedWork.actualStartTime,
@@ -734,15 +745,15 @@ function commitLifeCycles(
             if (enableSchedulerTracing) {
               onCommit(
                 finishedWork.memoizedProps.id,
-                current === null ? 'mount' : 'update',
+                phase,
                 effectDuration,
                 commitTime,
                 finishedRoot.memoizedInteractions,
               );
             } else {
               onCommit(
                 finishedWork.memoizedProps.id,
-                current === null ? 'mount' : 'update',
+                phase,
                 effectDuration,
                 commitTime,
               );

packages/react-reconciler/src/ReactFiberWorkLoop.new.js

@@ -21,6 +21,7 @@ import {
   enableSuspenseServerRenderer,
   replayFailedUnitOfWorkWithInvokeGuardedCallback,
   enableProfilerTimer,
+  enableProfilerNestedUpdatePhase,
   enableSchedulerTracing,
   warnAboutUnmockedScheduler,
   deferRenderPhaseUpdateToNextBatch,
@@ -195,9 +196,11 @@ import {
 } from './ReactFiberStack.new';
 
 import {
+  markNestedUpdateScheduled,
   recordCommitTime,
   startProfilerTimer,
   stopProfilerTimerIfRunningAndRecordDelta,
+  syncNestedUpdateFlag,
 } from './ReactProfilerTimer.new';
 
 // DEV stuff
@@ -714,6 +717,10 @@ function ensureRootIsScheduled(root: FiberRoot, currentTime: number) {
 // This is the entry point for every concurrent task, i.e. anything that
 // goes through Scheduler.
 function performConcurrentWorkOnRoot(root) {
+  if (enableProfilerTimer && enableProfilerNestedUpdatePhase) {
+    syncNestedUpdateFlag();
+  }
+
   // Since we know we're in a React event, we can clear the current
   // event time. The next update will compute a new event time.
   currentEventTime = NoTimestamp;
@@ -939,6 +946,10 @@ function markRootSuspended(root, suspendedLanes) {
 // This is the entry point for synchronous tasks that don't go
 // through Scheduler
 function performSyncWorkOnRoot(root) {
+  if (enableProfilerTimer && enableProfilerNestedUpdatePhase) {
+    syncNestedUpdateFlag();
+  }
+
   invariant(
     (executionContext & (RenderContext | CommitContext)) === NoContext,
     'Should not already be working.',
@@ -1996,6 +2007,10 @@ function commitRootImpl(root, renderPriorityLevel) {
   }
 
   if (remainingLanes === SyncLane) {
+    if (enableProfilerTimer && enableProfilerNestedUpdatePhase) {
+      markNestedUpdateScheduled();
+    }
+
     // Count the number of times the root synchronously re-renders without
     // finishing. If there are too many, it indicates an infinite update loop.
     if (root === rootWithNestedUpdates) {

packages/react-reconciler/src/ReactFiberWorkLoop.old.js

@@ -22,6 +22,7 @@ import {
   replayFailedUnitOfWorkWithInvokeGuardedCallback,
   enableProfilerTimer,
   enableProfilerCommitHooks,
+  enableProfilerNestedUpdatePhase,
   enableSchedulerTracing,
   warnAboutUnmockedScheduler,
   deferRenderPhaseUpdateToNextBatch,
@@ -207,11 +208,13 @@ import {
 } from './ReactFiberStack.old';
 
 import {
+  markNestedUpdateScheduled,
   recordCommitTime,
   recordPassiveEffectDuration,
   startPassiveEffectTimer,
   startProfilerTimer,
   stopProfilerTimerIfRunningAndRecordDelta,
+  syncNestedUpdateFlag,
 } from './ReactProfilerTimer.old';
 
 // DEV stuff
@@ -737,6 +740,10 @@ function ensureRootIsScheduled(root: FiberRoot, currentTime: number) {
 // This is the entry point for every concurrent task, i.e. anything that
 // goes through Scheduler.
 function performConcurrentWorkOnRoot(root) {
+  if (enableProfilerTimer && enableProfilerNestedUpdatePhase) {
+    syncNestedUpdateFlag();
+  }
+
   // Since we know we're in a React event, we can clear the current
   // event time. The next update will compute a new event time.
   currentEventTime = NoTimestamp;
@@ -962,6 +969,10 @@ function markRootSuspended(root, suspendedLanes) {
 // This is the entry point for synchronous tasks that don't go
 // through Scheduler
 function performSyncWorkOnRoot(root) {
+  if (enableProfilerTimer && enableProfilerNestedUpdatePhase) {
+    syncNestedUpdateFlag();
+  }
+
   invariant(
     (executionContext & (RenderContext | CommitContext)) === NoContext,
     'Should not already be working.',
@@ -2189,6 +2200,10 @@ function commitRootImpl(root, renderPriorityLevel) {
   }
 
   if (remainingLanes === SyncLane) {
+    if (enableProfilerTimer && enableProfilerNestedUpdatePhase) {
+      markNestedUpdateScheduled();
+    }
+
     // Count the number of times the root synchronously re-renders without
     // finishing. If there are too many, it indicates an infinite update loop.
     if (root === rootWithNestedUpdates) {

packages/react-reconciler/src/ReactProfilerTimer.new.js

@@ -10,8 +10,9 @@
 import type {Fiber} from './ReactInternalTypes';
 
 import {
-  enableProfilerTimer,
   enableProfilerCommitHooks,
+  enableProfilerNestedUpdatePhase,
+  enableProfilerTimer,
 } from 'shared/ReactFeatureFlags';
 import {Profiler} from './ReactWorkTags';
 
@@ -23,10 +24,13 @@ const {unstable_now: now} = Scheduler;
 
 export type ProfilerTimer = {
   getCommitTime(): number,
+  isCurrentUpdateNested(): boolean,
+  markNestedUpdateScheduled(): void,
   recordCommitTime(): void,
   startProfilerTimer(fiber: Fiber): void,
   stopProfilerTimerIfRunning(fiber: Fiber): void,
   stopProfilerTimerIfRunningAndRecordDelta(fiber: Fiber): void,
+  syncNestedUpdateFlag(): void,
   ...
 };
 
@@ -35,6 +39,42 @@ let layoutEffectStartTime: number = -1;
 let profilerStartTime: number = -1;
 let passiveEffectStartTime: number = -1;
 
+/**
+ * Tracks whether the current update was a nested/cascading update (scheduled from a layout effect).
+ *
+ * The overall sequence is:
+ *   1. render
+ *   2. commit (and call `onRender`, `onCommit`)
+ *   3. check for nested updates
+ *   4. flush passive effects (and call `onPostCommit`)
+ *
+ * Nested updates are identified in step 3 above,
+ * but step 4 still applies to the work that was just committed.
+ * We use two flags to track nested updates then:
+ * one tracks whether the upcoming update is a nested update,
+ * and the other tracks whether the current update was a nested update.
+ * The first value gets synced to the second at the start of the render phase.
+ */
+let currentUpdateIsNested: boolean = false;
+let nestedUpdateScheduled: boolean = false;
+
+function isCurrentUpdateNested(): boolean {
+  return currentUpdateIsNested;
+}
+
+function markNestedUpdateScheduled(): void {
+  if (enableProfilerNestedUpdatePhase) {
+    nestedUpdateScheduled = true;
+  }
+}
+
+function syncNestedUpdateFlag(): void {
+  if (enableProfilerNestedUpdatePhase) {
+    currentUpdateIsNested = nestedUpdateScheduled;
+    nestedUpdateScheduled = false;
+  }
+}
+
 function getCommitTime(): number {
   return commitTime;
 }
@@ -161,6 +201,8 @@ function transferActualDuration(fiber: Fiber): void {
 
 export {
   getCommitTime,
+  isCurrentUpdateNested,
+  markNestedUpdateScheduled,
   recordCommitTime,
   recordLayoutEffectDuration,
   recordPassiveEffectDuration,
@@ -169,5 +211,6 @@ export {
   startProfilerTimer,
   stopProfilerTimerIfRunning,
   stopProfilerTimerIfRunningAndRecordDelta,
+  syncNestedUpdateFlag,
   transferActualDuration,
 };