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

rickhanlonii · 2025-01-13T17:13:46Z

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

@@ -369,7 +369,7 @@ root.render(<App />);
 The <CodeStep step={1}>onUncaughtError</CodeStep> option is a function called with two arguments:

 1. The <CodeStep step={2}>error</CodeStep> that was thrown.
-2. An <CodeStep step={3}>errorInfo</CodeStep> object that contains the <CodeStep step={4}>componentStack</CodeStep> of the error.
+2. An <CodeStep step={3}>errorInfo</CodeStep> object that contains the parent Component stack in <CodeStep step={4}>componentStack</CodeStep> of the error.


The capitalization of only "Component" seems weird, seems like it should either be Component Stack or component stack.

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

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:20:59Z

src/content/reference/react/captureOwnerStack.md

+
+Neither `Navigation` nor `legend` are in the stack at all since it's only a sibling to a node containing `<SubComponent />`.
+
+### When to use which {/*when-to-use-which*/}


This explanation seems too technical to really understand when to use each. This is more "what they represent" and not "when to use". It's not really an either/or either. Owner stacks can be added in addition to component stacks when you're in DEV and want to add additional debugging info.

It's not really an either/or either.

I agree. This is not what I wanted to convey with this section.

Removed the section. It didn't really say anything new we already explained earlier.

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 <rickhanlonii@fb.com>

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"`

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 <rickhanlonii@fb.com>

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

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 14, 2025

rickhanlonii Jan 13, 2025

eps1lon Jan 14, 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


		Neither `Navigation` nor `legend` are in the stack at all since it's only a sibling to a node containing `<SubComponent />`.

		### When to use which {/when-to-use-which/}


		<Intro>

		`captureOwnerStack` reads the current owner Component stack and returns it as a string if 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

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

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