Add "nested-update" phase to Profiler API

[bvaughn]

Background

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 and block the main (JavaScript) thread, 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 PR updates the Profiler API to explicitly flag nested updates so they can be monitored for and avoided when possible.

API

I considered a few approaches for this.

1. Add a new callback (e.g. onNestedUpdateScheduled) to the Profiler that gets called when a nested updates gets scheduled.
2. Add an additional boolean parameter to the end of existing callbacks (e.g. wasNestedUpdate).
3. Update the phase param to add an additional variant: "mount", "update", or "nested-update" (new).

I think the third option makes for the best API so that's what I've implemented in this PR.

Because the Profiler API is stable, this change will need to remain behind a feature flag until v18. I've turned the feature flag on for Facebook builds though after confirming that Web Speed does not currently make use of the phase parameter.

Quirks

One quirk about the implementation I've chosen is that errors thrown during the layout phase are also reported as nested updates. I believe this is appropriate since these errors get processed synchronously and block paint. Errors thrown during render or from within passive effects are not affected by this change.

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 01c6228:

Sandbox	Source
React	Configuration

[sizebot]

Details of bundled changes.

Comparing: 6b28eb6...01c6228

react-dom

File	Filesize Diff	Gzip Diff	Prev Size	Current Size	Prev Gzip	Current Gzip	ENV
react-dom.development.js	-0.0%	-0.0%	903.53 KB	903.49 KB	205.6 KB	205.58 KB	NODE_DEV
ReactDOMForked-profiling.js	+0.1%	+0.1%	387.41 KB	387.7 KB	71.8 KB	71.89 KB	FB_WWW_PROFILING
react-dom-server.browser.development.js	0.0%	-0.0%	144.37 KB	144.37 KB	36.71 KB	36.71 KB	UMD_DEV
ReactDOMTesting-dev.js	-0.0%	-0.0%	907.9 KB	907.83 KB	204.51 KB	204.49 KB	FB_WWW_DEV
ReactDOMTesting-prod.js	0.0%	-0.0%	368.41 KB	368.41 KB	69.77 KB	69.77 KB	FB_WWW_PROD
react-dom-unstable-fizz.node.development.js	0.0%	+0.1%	5.35 KB	5.35 KB	1.8 KB	1.8 KB	NODE_DEV
react-dom-unstable-fizz.browser.development.js	0.0%	+0.1%	4.6 KB	4.6 KB	1.64 KB	1.64 KB	NODE_DEV
react-dom.development.js	-0.0%	-0.0%	949.46 KB	949.42 KB	208.15 KB	208.14 KB	UMD_DEV
react-dom.production.min.js	0.0%	0.0%	121.34 KB	121.34 KB	39.85 KB	39.86 KB	UMD_PROD
ReactDOMForked-dev.js	+0.1%	+0.2%	965.51 KB	966.81 KB	214.36 KB	214.75 KB	FB_WWW_DEV
react-dom.profiling.min.js	0.0%	-0.0%	126.95 KB	126.95 KB	40.77 KB	40.77 KB	NODE_PROFILING
ReactDOM-dev.js	+0.1%	+0.2%	950.31 KB	951.65 KB	212.57 KB	212.97 KB	FB_WWW_DEV
ReactDOM-prod.js	0.0%	-0.0%	366.94 KB	366.94 KB	68.16 KB	68.16 KB	FB_WWW_PROD
ReactDOM-profiling.js	+0.1%	+0.1%	380.57 KB	380.8 KB	70.64 KB	70.74 KB	FB_WWW_PROFILING
ReactDOMServer-dev.js	0.0%	-0.0%	141.14 KB	141.14 KB	36.22 KB	36.22 KB	FB_WWW_DEV
ReactDOMServer-prod.js	0.0%	-0.0%	46.28 KB	46.28 KB	10.79 KB	10.79 KB	FB_WWW_PROD

react-art

File	Filesize Diff	Gzip Diff	Prev Size	Current Size	Prev Gzip	Current Gzip	ENV
ReactART-prod.js	0.0%	0.0%	230.11 KB	230.11 KB	40.86 KB	40.86 KB	FB_WWW_PROD
react-art.development.js	-0.0%	-0.0%	686.62 KB	686.58 KB	145.89 KB	145.88 KB	UMD_DEV
react-art.production.min.js	0.0%	-0.0%	110.63 KB	110.63 KB	34.4 KB	34.4 KB	UMD_PROD
react-art.development.js	-0.0%	-0.0%	588 KB	587.96 KB	128.04 KB	128.03 KB	NODE_DEV
react-art.production.min.js	0.0%	0.0%	75.52 KB	75.52 KB	23.46 KB	23.46 KB	NODE_PROD
ReactART-dev.js	+0.2%	+0.3%	617.37 KB	618.7 KB	131.48 KB	131.87 KB	FB_WWW_DEV

Size changes (experimental)

Generated by 🚫 dangerJS against 01c6228

[sizebot]

Details of bundled changes.

Comparing: 6b28eb6...01c6228

react-dom

File	Filesize Diff	Gzip Diff	Prev Size	Current Size	Prev Gzip	Current Gzip	ENV
react-dom.development.js	-0.0%	-0.0%	871.79 KB	871.75 KB	199.59 KB	199.57 KB	NODE_DEV
ReactDOMForked-profiling.js	+0.1%	+0.1%	398.78 KB	399.08 KB	73.58 KB	73.66 KB	FB_WWW_PROFILING
react-dom-server.browser.development.js	0.0%	-0.0%	142.78 KB	142.78 KB	36.51 KB	36.51 KB	UMD_DEV
ReactDOMTesting-dev.js	-0.0%	-0.0%	936.24 KB	936.17 KB	210.02 KB	210 KB	FB_WWW_DEV
react-dom-test-utils.development.js	0.0%	-0.0%	66.1 KB	66.1 KB	18.79 KB	18.79 KB	NODE_DEV
react-dom.development.js	-0.0%	-0.0%	916.16 KB	916.12 KB	202.11 KB	202.09 KB	UMD_DEV
ReactDOMForked-dev.js	+0.1%	+0.2%	991.09 KB	992.39 KB	219.15 KB	219.55 KB	FB_WWW_DEV
ReactDOM-dev.js	+0.1%	+0.2%	975.89 KB	977.23 KB	217.27 KB	217.67 KB	FB_WWW_DEV
ReactDOM-profiling.js	+0.1%	+0.1%	391.87 KB	392.11 KB	72.4 KB	72.49 KB	FB_WWW_PROFILING
ReactDOMServer-prod.js	0.0%	-0.0%	47.15 KB	47.15 KB	11 KB	11 KB	FB_WWW_PROD

react-art

File	Filesize Diff	Gzip Diff	Prev Size	Current Size	Prev Gzip	Current Gzip	ENV
ReactART-prod.js	0.0%	-0.0%	237.25 KB	237.25 KB	42.11 KB	42.11 KB	FB_WWW_PROD
react-art.development.js	-0.0%	-0.0%	663.72 KB	663.68 KB	141.46 KB	141.45 KB	UMD_DEV
react-art.development.js	-0.0%	-0.0%	566.17 KB	566.13 KB	123.67 KB	123.66 KB	NODE_DEV
react-art.production.min.js	0.0%	-0.0%	73.31 KB	73.31 KB	22.79 KB	22.79 KB	NODE_PROD
ReactART-dev.js	+0.2%	+0.3%	627.38 KB	628.71 KB	133.51 KB	133.9 KB	FB_WWW_DEV

Size changes (stable)

Generated by 🚫 dangerJS against 01c6228

[bgirard]

Because they delay paint

For us the motivation isn't so much that they delay execution, although in concurrent mode the update becomes blocking which isn't ideal if it's going to take a long time.

It's primarily that measuring this can give us a stable counter, compared to wall time at least, that points at anti-patterns. For example when hooks don't get their initial state correctly and use a layout effect to set their initial state:

function NeedlessNestedUpdateComponent(props) {
  const [val, setVal] = useState(null);
  useLayoutEffect(() => {
    setVal(props.initialVal);
  });
  return <ExpensiveNonMemoComponent/>;
}

Here these two components will render twice which is avoidable.

[bvaughn]

It's primarily that measuring this can give us a stable counter, compared to wall time at least, that points at anti-patterns...Here these two components will render twice which is avoidable.

I'm not sure I understand why this distinction is important 😅 The reason we'd call this an "anti-pattern" is primarily because it delays paint / blocks the main thread. (This is the main reason this check is for useLayoutEffect and not useEffect.) It's also less efficient but I think that's secondary.

[bgirard]

Yes, we agree here. I'm also focusing on the CPU burn aspect. Ideally ExpensiveNonMemoComponent is rendered once and not twice. Finding and fixing this anti-pattern would fix that.

[bvaughn]

Benoit and I chatted out of band about this and are on the same page.

I plan on posting another PR (stacked on top of this one) that adds an additional callback to the Profiler API to help identify which component triggers the nested update.

[rickhanlonii]

LGTM!

[rickhanlonii]

What are your thoughts on update-nested instead? That seems to read more like "Update (nested)" to me.

[bvaughn]

Hm. I think it reads a bit more awkward. When we talk about these things, we call them "nested updates".

[bvaughn]

Thanks for the stamp, Ricky!