Reference docs for experimental captureOwnerStack

[eps1lon]

Based on #7430

Preview:
captureOwnerStack
createRoot error handlers
hydrateRoot error handlers

The owner stack vs parent section probably deserves its own page since owner stacks also appear in devtools and console.createTask.

Should I just move this into a "debugging" section inside "learn"?

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
19-react-dev	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 23, 2025 2:40pm
react-dev	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 23, 2025 2:40pm

[github-actions]

Size changes

📦 Next.js Bundle Analysis for react-dev

This analysis was generated by the Next.js Bundle Analysis action. 🤖

One Page Changed Size

The following page changed size from the code in this PR compared to its base branch:

Page	Size (compressed)	First Load
/[[...markdownPath]]	126.95 KB (🟡 +16 B)	237.33 KB

Details

Only the gzipped size is provided here based on an expert tip.

First Load is the size of the global bundle plus the bundle for the individual page. If a user were to show up to your website and land on a given page, the first load size represents the amount of javascript that user would need to download. If next/link is used, subsequent page loads would only need to download that page's bundle (the number in the "Size" column), since the global bundle has already been downloaded.

Any third party scripts you have added directly to your app using the <script> tag are not accounted for in this analysis

Next to the size is how much the size has increased or decreased compared with the base branch of this PR. If this percentage has increased by 10% or more, there will be a red status indicator applied, indicating that special attention should be given to this.

[rickhanlonii]

I think the naming we should go with is:

• Component Stack: what you're calling "parent component stack" here
• Owner Stack: what you're calling "owner component stack" here

[rickhanlonii]

What is a "parent Component Stack" isn't that just the Component Stack? Adding "parent" makes it sound like it doesn't include the component that errored.

This page should also add a usage item for calling captureOwnerStack to get the owner stack.

[eps1lon]

I feel like expanding the existing usages is sufficient. Is that what you meant? Adding a whole new section feels like overkill.

[rickhanlonii]

Do we really recommend appending it to the existing stack? Won't that add it to the end?

IMO this should be like:

if (__DEV__) { 
  showDialog(error, ownerStack, componentStack);
} else {
  logProdError(error, componentStack);
}

[eps1lon]

We do that in Next.js and it's conceptually how you arrive at the error if every JSX callsite would just be a function call.

[sophiebits]

Aren't we getting rid of parent stacks entirely eventually? I thought the plan was for owner stacks to subsume them. In which case I might still discuss which stack frames you'll see but not emphasize the difference so much.

[sebmarkbage]

Aren't we getting rid of parent stacks entirely eventually? I thought the plan was for owner stacks to subsume them.

Not for production logging. They're the ones passed to the deriveStateFromError/componentDidCatch and onError on the server. They only go away in the standard DEV console.error reporting.

[rickhanlonii]

There should also be runable sandboxes for the Usage examples

[gaearon]

There should also be runable sandboxes for the Usage examples

To expand on that — it’s not just for it to be nice but because it’s a proof the API actually works end to end and does what the docs page says it does. We’ve had cases where that wasn’t the case and the Usage examples helped uncover the misunderstandings.

[rickhanlonii]

Suggested change

	`captureOwnerStack` was called outside of development builds.
	For performance reasons, React will not keep track of Owners in production.
	`captureOwnerStack` was called outside of development builds. For performance reasons, React will not keep track of Owner Stacks in production.

[eps1lon]

Done

[rickhanlonii]

Suggested change

	The call of `captureOwnerStack` happened outside of a React controlled function e.g. in a `setTimeout` callback.
	During render, Effects, Events, and React error handlers (e.g. `hydrateRoot#options.onCaughtError`) Owner Stacks should be available.
	The call of `captureOwnerStack` happened outside of a React controlled function e.g. in a `setTimeout` callback. During render, Effects, Events, and React error handlers (e.g. `hydrateRoot#options.onCaughtError`) Owner Stacks should be available.

And can we add a sandbox with the issue and fix?

[eps1lon]

Added one for custom DOM event handlers which is also a likely pitfall.

[rickhanlonii]

The other comments are nits, but I think there's a usage section still missing here for patching console.error. If you only instrument owner stacks for DEV dialogs in the root error handlers, you will miss owner stacks in console.error calls. So you need to patch console.error, but you need to patch it after dev tools, which is tricky to get right and needs docs.

[rickhanlonii]

If you've patched console.error to add owner stacks, and you call console.error here, it will result in multiple owner stacks being applied. It's not clear to me whether you should only patch console.error, or if you should instrument the root handlers and console.error without them overlapping somehow.

@sebmarkbage how should this work ideally? Maybe we're over-emphasizing the root handler case?

The way I expected this to work is like:

onUncaughtError() {
  if (process.env.NODE_ENV !== 'production') {
      const ownerStack = captureOwnerStack();
      sendDevOnlyLogs(error, ownerStack);
  } else {
    sendProductionLogs(error);
  }
  
  // Patch or DevTools will add logs to the console output.
  console.error(error);
}

[eps1lon]

Yeah I think the usage in error handlers is the better example. If there's a need to document polyfilling what React Devtools is doing, we can add it later. You only need to patch console if React Devtools is not available. Otherwise you'll get them either in the last arg or via createTask (whichever is available).