Reference docs for experimental `captureOwnerStack` #7427

eps1lon · 2025-01-13T14:03:30Z

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 · 2025-01-13T14:03:36Z

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 14, 2025 4:38pm
react-dev	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 14, 2025 4:38pm

github-actions · 2025-01-13T14:05:27Z

Size changes

📦 Next.js Bundle Analysis for react-dev

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

⚠️ Global Bundle Size Increased

Page	Size (compressed)
`global`	`110.38 KB` (🟡 +2 B)

Details

The global bundle is the javascript bundle that loads alongside every page. It is in its own category because its impact is much higher - an increase to its size means that every page on your website loads slower, and a decrease means every page loads faster.

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

If you want further insight into what is behind the changes, give @next/bundle-analyzer a try!

Five Pages Changed Size

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

Page	Size (compressed)	First Load
`/404`	`125.09 KB` (🟡 +18 B)	235.47 KB
`/500`	`125.09 KB` (🟡 +18 B)	235.48 KB
`/[[...markdownPath]]`	`126.97 KB` (🟡 +34 B)	237.35 KB
`/errors`	`125.37 KB` (🟡 +18 B)	235.75 KB
`/errors/[errorCode]`	`125.34 KB` (🟡 +18 B)	235.72 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 · 2025-01-13T17:10:33Z

src/content/reference/react-dom/client/createRoot.md

-  * **optional** `onCaughtError`: Callback called when React catches an error in an Error Boundary. Called with the `error` caught by the Error Boundary, and an `errorInfo` object containing the `componentStack`.
-  * **optional** `onUncaughtError`: Callback called when an error is thrown and not caught by an Error Boundary. Called with the `error` that was thrown, and an `errorInfo` object containing the `componentStack`.
-  * **optional** `onRecoverableError`: Callback called when React automatically recovers from errors. Called with an `error` React throws, and an `errorInfo` object containing the `componentStack`. Some recoverable errors may include the original error cause as `error.cause`.
+  * **optional** `onCaughtError`: Callback called when React catches an error in an Error Boundary. Called with the `error` caught by the Error Boundary, and an `errorInfo` object containing the parent Component stack in `componentStack`.


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.

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

src/content/reference/react/captureOwnerStack.md

src/content/reference/react-dom/client/createRoot.md

rickhanlonii · 2025-01-13T17:17:44Z

src/content/reference/react/captureOwnerStack.md

+If no owner stack is available, it returns an empty string.
+Outside of development builds, `null` is returned.
+
+## Owner Component stacks vs parent Component stacks {/*owner-component-stacks-vs-parent-component-stacks*/}


Let's wrap this in a <DeepDive />

src/content/reference/react/captureOwnerStack.md

rickhanlonii · 2025-01-13T17:22:50Z

src/content/reference/react/captureOwnerStack.md

+    onCaughtError: (error, errorInfo) => {
+      if (process.env.NODE_ENV !== 'production') {
+        const ownerStack = captureOwnerStack();
+        error.stack += ownerStack;


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); }

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.

rickhanlonii · 2025-01-13T17:24:07Z

src/content/reference/react/captureOwnerStack.md

+
+<Intro>
+
+`captureOwnerStack` reads the current **owner** Component stack and returns it as a string if available.


We should make it more clear that this is dev-only. I would mention it here, in a Caveat, and a Troubleshooting "My owner stacks are empty in production" section.

Did all that. Also explained this in the createRoot and hydrateRoot usage examples. Though possible I missed some spots.

sophiebits · 2025-01-13T17:51:33Z

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 · 2025-01-13T17:53:15Z

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 · 2025-01-13T18:50:34Z

There should also be runable sandboxes for the Usage examples

gaearon · 2025-01-14T04:28:27Z

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.

Forks on CodeSandbox will ignore `/index.html` and create their own `public/index.html` which leads to broken sandboxes in CodeSandbox. We now throw if `/index.html` is used and only use `public/index.html` which works both in Sandpack and CodeSandbox. This also means we're consistent. Some sandboxes were already using the functioning `public/index.html`.

Co-authored-by: Ricky <[email protected]>

parent Component stack -> Component Stack owner Component stack -> Owner Stack

Was just rephrasing what we already had and gave wrong impression

i.e. everywhere I found mention of `"componentStack"`

rickhanlonii · 2025-01-19T15:33:40Z

src/content/reference/react/captureOwnerStack.md

+
+<Wip>
+
+**This API is experimental and is not available in a stable version of React yet.**


I think we should update this to the Canary badge, and just wait until we add this to Canary to merge the docs.

rickhanlonii · 2025-01-19T15:41:06Z

src/content/reference/react/captureOwnerStack.md

+If no Owner Stack is available, it returns an empty string.
+Outside of development builds, `null` is returned.


Suggested change

If no Owner Stack is available, it returns an empty string.

Outside of development builds, `null` is returned.

If no Owner Stack is available, it returns an empty string. Outside of development builds, `null` is returned.

Also, instead of "if no owner stack is available" we should say when owner stacks are not available. Like maybe not too specific, but something like "if it's not called inside a component lifecycle".

We call this out in the troubleshooting section so we should just also include that explanation here.

rickhanlonii · 2025-01-19T15:43:06Z

src/content/reference/react/captureOwnerStack.md

+createRoot(document.createElement('div'), {
+  onUncaughtError: (error, errorInfo) => {
+    // The stacks are logged instead of showing them in the UI directly to highlight that browsers will apply sourcemaps to the logged stacks.
+    // Note that sourcemapping is only applied in the real browser console not in the fake one displayed on this page.


Would shorten the line length of this comment so you don't force a hscroll on desktop at least:

rickhanlonii · 2025-01-19T15:47:01Z

src/content/reference/react/captureOwnerStack.md

+    console.log(errorInfo.componentStack);
+    console.log(captureOwnerStack());


Would add labels:

Suggested change

console.log(errorInfo.componentStack);

console.log(captureOwnerStack());

console.log('Component Stack:', errorInfo.componentStack);

console.log('Owner Stack:', captureOwnerStack());

rickhanlonii · 2025-01-19T15:50:51Z

src/content/reference/react/captureOwnerStack.md

+`SubComponent` would throw an error.
+The Component Stack of that error would be


I've seen this in a few places - think there's way too many newlines in these docs, instead I would write it more paragraph style:

Suggested change

`SubComponent` would throw an error.

The Component Stack of that error would be

`SubComponent` would throw an error. The Component Stack of that error would be:

But you should also expand here, because it's not clear what SubComponent is:

Suggested change

`SubComponent` would throw an error.

The Component Stack of that error would be

In this example, `SubComponent` throws an error in render, which is not caught by an error boundary. The root `onUncaughtError` method is called, and logs the Component Stack and Owner Stack. The Component Stack of that error is:

rickhanlonii · 2025-01-19T15:54:33Z

src/content/reference/react/captureOwnerStack.md

+
+## Usage {/*usage*/}
+
+### Improve error reporting {/*improve-error-reporting*/}


When I read this and the usage below, I hear "reporting for production logging" which isn't the case. I really think the usages here are limited to just instrumenting DEV dialogs.

rickhanlonii · 2025-01-19T15:55:23Z

src/content/reference/react/captureOwnerStack.md

+  onUncaughtError: (error, errorInfo) => {
+    if (process.env.NODE_ENV !== 'production') {
+      const ownerStack = captureOwnerStack();
+      error.stack += ownerStack;


Why would you do this? Isn't it already in the stack if you have DevTools open? And if DevTools is open, won't this double add the owner stack?

rickhanlonii · 2025-01-19T15:57:09Z

src/content/reference/react/captureOwnerStack.md

+        // The stack is only split because these sandboxes don't implement ignore-listing 3rd party frames via sourcemaps.
+        // A framework would ignore-list stackframes from React via sourcemaps and then you could just `error.stack += ownerStack`.
+        // To learn more about ignore-listing see https://developer.chrome.com/docs/devtools/x-google-ignore-list
+        error.stack.split('\n    at react-stack-bottom-frame')[0] + ownerStack;


This should be a separate usage section like "How to collapse frames in DEV dialogs without sourcemaps"

Or maybe Troubleshooting

This also seems weird to me because React DevTools adds the owner stack in the stack trace? Why would you want to do this?

rickhanlonii · 2025-01-19T16:07:50Z

src/content/reference/react/captureOwnerStack.md

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


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.

rickhanlonii · 2025-01-19T16:08:27Z

src/content/reference/react/captureOwnerStack.md

+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.


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?

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 · 2025-01-19T16:17:07Z

src/content/reference/react/captureOwnerStack.md

+
+    // The stacks are logged instead of showing them in the UI directly to highlight that browsers will apply sourcemaps to the logged stacks.
+    // Note that sourcemapping is only applied in the real browser console not in the fake one displayed on this page.
+    console.error('Uncaught', error);


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); }

vercel bot deployed to Preview – 19-react-dev January 13, 2025 14:03 View deployment

facebook-github-bot added CLA Signed React Core Team labels Jan 13, 2025

eps1lon force-pushed the sebbie/ownerstacks branch from 4a08a62 to 4bf159b Compare January 13, 2025 14:08

vercel bot deployed to Preview – react-dev January 13, 2025 14:09 View deployment

vercel bot deployed to Preview – 19-react-dev January 13, 2025 14:09 View deployment

eps1lon marked this pull request as ready for review January 13, 2025 14:21

eps1lon requested review from rickhanlonii and sebmarkbage January 13, 2025 14:21

eps1lon mentioned this pull request Jan 13, 2025

Enable owner stacks in Canary builds facebook/react#32053

Open

vercel bot deployed to Preview – 19-react-dev January 13, 2025 15:28 View deployment

vercel bot deployed to Preview – react-dev January 13, 2025 15:28 View deployment

rickhanlonii reviewed Jan 13, 2025

View reviewed changes

vercel bot deployed to Preview – react-dev January 14, 2025 09:01 View deployment

vercel bot deployed to Preview – 19-react-dev January 14, 2025 09:01 View deployment

eps1lon and others added 9 commits January 14, 2025 16:49

Reference docs for captureOwnerStack

3adbd12

Differentiate parent and owner stacks throughout docs

b1d919b

null outside of dev

300f8df

Update src/content/reference/react/captureOwnerStack.md

c63b1ec

Co-authored-by: Ricky <[email protected]>

New terminology

898e568

parent Component stack -> Component Stack owner Component stack -> Owner Stack

Emphasize dev-only nature

538b3cf

Remove "When to use which"

6f983c3

Was just rephrasing what we already had and gave wrong impression

move parent vs owner into DeepDive

267c0f5

eps1lon force-pushed the sebbie/ownerstacks branch from d6e8d90 to 4f59d78 Compare January 14, 2025 15:59

vercel bot deployed to Preview – 19-react-dev January 14, 2025 16:01 View deployment

vercel bot deployed to Preview – react-dev January 14, 2025 16:01 View deployment

eps1lon force-pushed the sebbie/ownerstacks branch from 4f59d78 to 265786e Compare January 14, 2025 16:07

vercel bot deployed to Preview – react-dev January 14, 2025 16:08 View deployment

vercel bot deployed to Preview – 19-react-dev January 14, 2025 16:08 View deployment

Move code into sandboxes

4b1f5cb

eps1lon force-pushed the sebbie/ownerstacks branch from 265786e to 47e7e41 Compare January 14, 2025 16:15

vercel bot deployed to Preview – react-dev January 14, 2025 16:16 View deployment

vercel bot deployed to Preview – 19-react-dev January 14, 2025 16:16 View deployment

Include captureOwnerStack in error handling examples

08b6a85

i.e. everywhere I found mention of `"componentStack"`

eps1lon force-pushed the sebbie/ownerstacks branch from 47e7e41 to 08b6a85 Compare January 14, 2025 16:37

vercel bot deployed to Preview – react-dev January 14, 2025 16:38 View deployment

vercel bot deployed to Preview – 19-react-dev January 14, 2025 16:38 View deployment

eps1lon requested a review from rickhanlonii January 14, 2025 16:38

rickhanlonii reviewed Jan 19, 2025

View reviewed changes

rickhanlonii requested changes Jan 19, 2025

View reviewed changes

rickhanlonii reviewed Jan 19, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Reference docs for experimental `captureOwnerStack` #7427

Reference docs for experimental `captureOwnerStack` #7427

eps1lon commented Jan 13, 2025 •

edited

Loading

vercel bot commented Jan 13, 2025 •

edited

Loading

github-actions bot commented Jan 13, 2025 •

edited

Loading

📦 Next.js Bundle Analysis for react-dev

⚠️ Global Bundle Size Increased

Five Pages Changed Size

rickhanlonii left a comment

rickhanlonii Jan 13, 2025

eps1lon Jan 14, 2025

rickhanlonii Jan 13, 2025

eps1lon Jan 14, 2025

rickhanlonii Jan 13, 2025

eps1lon Jan 13, 2025

rickhanlonii Jan 13, 2025

eps1lon Jan 14, 2025

sophiebits commented Jan 13, 2025

sebmarkbage commented Jan 13, 2025 •

edited

Loading

rickhanlonii commented Jan 13, 2025

gaearon commented Jan 14, 2025

rickhanlonii Jan 19, 2025

rickhanlonii Jan 19, 2025

rickhanlonii Jan 19, 2025

rickhanlonii Jan 19, 2025

rickhanlonii Jan 19, 2025

rickhanlonii Jan 19, 2025

rickhanlonii Jan 19, 2025

rickhanlonii Jan 19, 2025

rickhanlonii Jan 19, 2025

rickhanlonii Jan 19, 2025

rickhanlonii Jan 19, 2025

rickhanlonii Jan 19, 2025

rickhanlonii Jan 19, 2025

rickhanlonii left a comment

rickhanlonii Jan 19, 2025 •

edited

Loading


		<Intro>

		`captureOwnerStack` reads the current owner Component stack and returns it as a string if available.


		<Wip>

		This API is experimental and is not available in a stable version of React yet.

		If no Owner Stack is available, it returns an empty string.
		Outside of development builds, `null` is returned.

		console.log(errorInfo.componentStack);
		console.log(captureOwnerStack());

		`SubComponent` would throw an error.
		The Component Stack of that error would be

	`SubComponent` would throw an error.
	The Component Stack of that error would be
	`SubComponent` would throw an error. The Component Stack of that error would be:

	`SubComponent` would throw an error.
	The Component Stack of that error would be
	In this example, `SubComponent` throws an error in render, which is not caught by an error boundary. The root `onUncaughtError` method is called, and logs the Component Stack and Owner Stack. The Component Stack of that error is:


		## Usage {/usage/}

		### Improve error reporting {/improve-error-reporting/}

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

		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.

Reference docs for experimental captureOwnerStack #7427

Are you sure you want to change the base?

Reference docs for experimental captureOwnerStack #7427

Conversation

eps1lon commented Jan 13, 2025 • edited Loading

vercel bot commented Jan 13, 2025 • edited Loading

github-actions bot commented Jan 13, 2025 • edited Loading

Size changes

📦 Next.js Bundle Analysis for react-dev

⚠️ Global Bundle Size Increased

Five Pages Changed Size

rickhanlonii left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sophiebits commented Jan 13, 2025

sebmarkbage commented Jan 13, 2025 • edited Loading

rickhanlonii commented Jan 13, 2025

gaearon commented Jan 14, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rickhanlonii left a comment

Choose a reason for hiding this comment

rickhanlonii Jan 19, 2025 • edited Loading

Choose a reason for hiding this comment

Reference docs for experimental `captureOwnerStack` #7427

Reference docs for experimental `captureOwnerStack` #7427

eps1lon commented Jan 13, 2025 •

edited

Loading

vercel bot commented Jan 13, 2025 •

edited

Loading

github-actions bot commented Jan 13, 2025 •

edited

Loading

sebmarkbage commented Jan 13, 2025 •

edited

Loading

rickhanlonii Jan 19, 2025 •

edited

Loading