Improving the component logging/debugging experience

[bvaughn]

Backstory

DevTools re-renders function components that use hooks in order to build up metadata to display in the selected element panel. This may cause confusion, since these re-renders will trigger breakpoints and cause unexpected console logging (see this comment). We avoid unnecessary re-renders by caching data (see PR 289) but even so this is likely to be a point of confusion.

Solution

It would be nice if the shallow re-rendering done by DevTools were less observable (e.g. console logs were suppressed to avoid cluttering the console). Breakpoints would still be hit, but that seems like a less common use case.

While we are considering logging, we might also consider if there are additional improvements that could be made, e.g.

1. Add a new section to the Components tree that shows the most recently logged messages for a given component.
2. Add an option to coalesce render-time logs into a single message that's printed at commit (or error) time to make debug logging easier to read. (Perhaps we could use console.group to also indicate the nested structure of these logs.)

The proposals below address both (a) collecting per-component logging info and (b) temporarily disabling console logging while re-rendering for inspection purposes.

API Proposals

1: Modify built-in console methods

DevTools could spy on the built-in console methods and disable the pass-through functionality when re-rendering.

Pros

• Requires no effort / code changes for developers to opt in and benefit from this.
• "Just works" for advanced methods like console.group and console.table.
• "Just works" for third party libraries that may not even be React-specific.

Cons

• Feels questionable to modify native browser APIs.

2: Add React.log and React.info API

React will be adding two new logging methods in the upcoming v16.9 release- React.warn and React.error (see #15170). These methods decorate console.warn and console.error and append the current component stack to any logged messages. We could extend this pattern and add additional log and info methods. These APIs could be extended by DevTools as needed.

Pros

• Does not require mutating global APIs.

Cons

• Requires code changes to opt-in.
• Would not cover (or would be a hassle to cover) all console methods (e.g. group)
• Would not work for third party components or non-React utility code.

3: Add React.debug(callback) API

React could add a new debug API that accepts a callback for general debug operations (most commonly console logging, but also potentially breakpoints or other things).

Pros

• Works with breakpoints.
• Covers more complex use cases (e.g. pushing to an array for debug purposes).
• Single method rather than mirroring (or spying on) multiple console APIs.

Cons

• Requires code changes to opt-in.
• Requires more boilerplate for simple logging use cases.

[bvaughn]

I think my personal preference, after a little consideration, is the third option- React.debug(callback)

[sompylasar]

I think the proposal tries to fight with the call side-effects (logging, hitting breakpoints) but does not address the original problem that DevTools is solving, which is "DevTools re-renders function components that use hooks in order to build up metadata to display in the selected element panel." – why doesn't React expose getting this required metadata as an API, so it forces DevTools to use workarounds to gather hooks information (call the components and thus trigger their call side-effects)?

[bvaughn]

why doesn't React expose getting this required metadata as an API, so it forces DevTools to use workarounds to gather hooks information

There are two reasons for this design:

• DevTools needs a lot more information than React does. For example, it's useful for DevTools to be able to identify and display "custom hooks" (functions with names that start with "use" that call other hooks). Identifying custom hooks relies on the relatively "expensive" operation of parsing the call stack.
• Even for built in hooks, we would not want to add additional overhead to React for every component that uses hooks just to support the uncommon case of displaying hooks values for a component selected in DevTools at some point in time.

For what it's worth, I agree with the general sentiment that it's unfortunate (and a bit awkward) that DevTools needs to shallow render a component to read hooks values. I think it's probably still the right trade off though, given the above considerations.

[sebmarkbage]

@sompylasar Fixing that also doesn't fix the other issue. React recalls functions multiple times during DEV mode and in concurrent mode can rebase and call the function multiple times for a single render. The contract is that we can call the function as much as we want without side-effects.

[bvaughn]

I think the original DevTools behavior that felt particularly broken was that we polled the component once a second. So it felt like there was an infinite loop. Now that we cache the results and only invalidate when the component is updated, it will "feel" more inline with React's normal rendering flow.

[sompylasar]

React recalls functions multiple times during DEV mode and in concurrent mode can rebase and call the function multiple times for a single render. The contract is that we can call the function as much as we want without side-effects.

This is somewhat expected because this is not a part of debugging, it's a part of the program being debugged. Ideally a debugger does not alter the behavior of the program being debugged, and that is what I am concerned about with renders being called more than usual when DevTools is present.

[davidmccabe]

I don't think you should try to conceal that you're calling the function extra times -- this is just going to lead to major confusion when somebody has a side-effect in their function. And debugging is exactly the time that they're going to do that, because they're putting in temporary hacks to figure out what's going on.

[bvaughn]

this is just going to lead to major confusion when somebody has a side-effect in their function.

Shallow rendering a component should not trigger any side effects¹. Those should be in useEffect / useLayoutEffect (which DevTools would not execute).

¹ - Technically calling console.log is a side effect but I think it's also a bit of a special case.