add component stack frames + tests

Author: Sébastien Henau

.claude/docs/projects - react-improvements.md

@@ -11,13 +11,17 @@
 - [x] FlareErrorBoundary `onReset` passes previous error
 - [x] FlareErrorBoundary supports `resetKeys` property
 - [x] Add `flareReactErrorHandler`
+- [x] Structured component stack parsing with sourcemap-ready frames
 
 ## FlareErrorBoundary: `fallback` property
 
 ### Inspiration
 
-- [Sentry ErrorBoundary `fallback`](https://docs.sentry.io/platforms/javascript/guides/react/features/error-boundary/#fallback-ui-options) -- supports a static element and a render function receiving `{ error, componentStack, resetError }`
-- [react-error-boundary](https://github.com/bvaughn/react-error-boundary) -- the most popular standalone error boundary library, supports `fallback`, `fallbackRender`, and `FallbackComponent` as three separate props
+- [Sentry ErrorBoundary
+  `fallback`](https://docs.sentry.io/platforms/javascript/guides/react/features/error-boundary/#fallback-ui-options) --
+  supports a static element and a render function receiving `{ error, componentStack, resetError }`
+- [react-error-boundary](https://github.com/bvaughn/react-error-boundary) -- the most popular standalone error boundary
+  library, supports `fallback`, `fallbackRender`, and `FallbackComponent` as three separate props
 
 ### Why
 
@@ -55,9 +59,11 @@ The `fallback` prop accepts either a static `ReactNode` or a render function. Th
 
 ### Inspiration
 
-- [Sentry ErrorBoundary `onError`](https://docs.sentry.io/platforms/javascript/guides/react/features/error-boundary/#options-reference) -- called when the boundary encounters an error
-- [react-error-boundary `onError`](https://github.com/bvaughn/react-error-boundary?tab=readme-ov-file#onerror) -- same concept, receives `(error, info)`
-
+- [Sentry ErrorBoundary
+  `onError`](https://docs.sentry.io/platforms/javascript/guides/react/features/error-boundary/#options-reference) --
+  called when the boundary encounters an error
+- [react-error-boundary `onError`](https://github.com/bvaughn/react-error-boundary?tab=readme-ov-file#onerror) -- same
+  concept, receives `(error, info)`
 
 ### Why
 
@@ -79,7 +85,9 @@ showing a toast, updating app state, etc. This fires *after* the error has been
 
 ### Inspiration
 
-- [Sentry ErrorBoundary `beforeCapture`](https://docs.sentry.io/platforms/javascript/guides/react/features/error-boundary/#options-reference) -- the only competitor that offers this; receives the Sentry scope to set tags and context before the event is sent
+- [Sentry ErrorBoundary
+  `beforeCapture`](https://docs.sentry.io/platforms/javascript/guides/react/features/error-boundary/#options-reference) --
+  the only competitor that offers this; receives the Sentry scope to set tags and context before the event is sent
 
 No other competitor (Datadog, Bugsnag, Rollbar, LogRocket) provides an equivalent hook.
 
@@ -104,8 +112,11 @@ the developer decide what to include rather than trying to automatically seriali
 
 ### Inspiration
 
-- [react-error-boundary `onReset`](https://github.com/bvaughn/react-error-boundary?tab=readme-ov-file#onreset) -- the primary inspiration; called when the boundary resets, receives details about what triggered the reset
-- [Sentry ErrorBoundary `onReset`](https://github.com/getsentry/sentry-javascript/blob/master/packages/react/src/errorboundary.tsx) -- exists in Sentry's source code (receives `error, componentStack, eventId`) but is not documented in their official docs
+- [react-error-boundary `onReset`](https://github.com/bvaughn/react-error-boundary?tab=readme-ov-file#onreset) -- the
+  primary inspiration; called when the boundary resets, receives details about what triggered the reset
+- [Sentry ErrorBoundary
+  `onReset`](https://github.com/getsentry/sentry-javascript/blob/master/packages/react/src/errorboundary.tsx) -- exists
+  in Sentry's source code (receives `error, componentStack, eventId`) but is not documented in their official docs
 
 ### Why
 
@@ -131,7 +142,8 @@ error allows conditional cleanup based on what went wrong.
 
 ### Inspiration
 
-- [react-error-boundary `resetKeys`](https://github.com/bvaughn/react-error-boundary?tab=readme-ov-file#resetkeys) -- the sole source for this pattern; Sentry does not offer it
+- [react-error-boundary `resetKeys`](https://github.com/bvaughn/react-error-boundary?tab=readme-ov-file#resetkeys) --
+  the sole source for this pattern; Sentry does not offer it
 
 This is a feature unique to react-error-boundary that neither Sentry nor any other error tracking competitor provides.
 When any value in the `resetKeys` array changes between renders (compared via `Object.is`), the boundary automatically
@@ -165,8 +177,11 @@ function App() {
 
 ### Inspiration
 
-- [Sentry `reactErrorHandler`](https://docs.sentry.io/platforms/javascript/guides/react/features/error-boundary/#error-hooks-vs-errorboundary) -- provides `Sentry.reactErrorHandler()` for all three React 19 root error hooks, with an optional callback parameter
-- [React 19 `createRoot` error handling docs](https://react.dev/reference/react-dom/client/createRoot#parameters) -- the React docs describing `onCaughtError`, `onUncaughtError`, and `onRecoverableError`
+- [Sentry
+  `reactErrorHandler`](https://docs.sentry.io/platforms/javascript/guides/react/features/error-boundary/#error-hooks-vs-errorboundary) --
+  provides `Sentry.reactErrorHandler()` for all three React 19 root error hooks, with an optional callback parameter
+- [React 19 `createRoot` error handling docs](https://react.dev/reference/react-dom/client/createRoot#parameters) -- the
+  React docs describing `onCaughtError`, `onUncaughtError`, and `onRecoverableError`
 
 Our API mirrors Sentry's approach: a wrapper function that accepts an optional callback. The key difference is that
 `flareReactErrorHandler` also handles non-Error values (strings, objects) by converting them to proper Error instances
@@ -198,4 +213,77 @@ const root = createRoot(document.getElementById('root')!, {
 });
 
 root.render(<App />);
-```
+```
+
+## Structured component stack parsing with sourcemap-ready frames
+
+### Inspiration
+
+- [Sentry
+  `captureReactException`](https://github.com/getsentry/sentry-javascript/blob/master/packages/react/src/error.ts) --
+  creates a synthetic Error with the raw `componentStack` as its `.stack` property and links it to the original error
+  via `error.cause`; server-side sourcemap processing then applies to this synthetic stack trace
+- [Bugsnag `formatComponentStack`](https://github.com/bugsnag/bugsnag-js/tree/main/packages/plugin-react) -- only trims
+  whitespace; sends componentStack as raw metadata; has
+  an [open feature request (issue #2097)](https://github.com/bugsnag/bugsnag-js/issues/2097) to apply sourcemaps to it
+- Rollbar and LogRocket do not parse or sourcemap the componentStack at all
+
+### Why
+
+React's `ErrorInfo.componentStack` is a raw multiline string whose format differs between browser engines:
+
+- **Chromium** (Chrome, Edge, Opera, Brave): `at ComponentName (http://localhost:5173/src/App.tsx:12:9)`
+- **Firefox/Safari** (Gecko, WebKit): `ComponentName@http://localhost:5173/src/App.tsx:12:9`
+
+Previously, `formatComponentStack()` just split this string by newlines into a `string[]`, giving the Flare dashboard
+nothing structured to work with. By parsing each line into `{ component, file, line, column }` objects, we give the
+backend clean structured data for sourcemap resolution and rich dashboard rendering (clickable source links, component
+tree views, searchable component names) -- without requiring the backend to re-parse a raw string or a synthetic stack
+trace like Sentry does.
+
+Both `componentStack` (original `string[]`) and `componentStackFrames` (new `ComponentStackFrame[]`) are sent in the
+report context for backwards compatibility. The backend can adopt the structured format when ready.
+
+### Report context structure
+
+```json
+{
+  "context": {
+    "react": {
+      "componentStack": [
+        "at ErrorComponent (http://localhost:5173/src/App.tsx:12:9)",
+        "at div",
+        "at App (http://localhost:5173/src/App.tsx:5:3)"
+      ],
+      "componentStackFrames": [
+        {
+          "component": "ErrorComponent",
+          "file": "http://localhost:5173/src/App.tsx",
+          "line": 12,
+          "column": 9
+        },
+        {
+          "component": "div",
+          "file": null,
+          "line": null,
+          "column": null
+        },
+        {
+          "component": "App",
+          "file": "http://localhost:5173/src/App.tsx",
+          "line": 5,
+          "column": 3
+        }
+      ]
+    }
+  }
+}
+```
+
+### Backend requirements
+
+The Flare backend/dashboard needs to:
+
+1. Read `componentStackFrames` from the report context
+2. Apply sourcemap resolution to each frame's `file`/`line`/`column`
+3. Render the component stack as a structured list in the dashboard

packages/react/package.json

@@ -28,14 +28,16 @@
     "scripts": {
         "prepublishOnly": "npm run build",
         "build": "tsdown src/index.ts --format cjs,esm --dts --clean",
+        "test": "vitest run",
         "typescript": "tsc --noEmit"
     },
     "devDependencies": {
         "@flareapp/js": "file:../js",
         "@types/react": "^19.0.0",
         "react": "^19.0.0",
         "tsdown": "^0.20.3",
-        "typescript": "^5.7.0"
+        "typescript": "^5.7.0",
+        "vitest": "^3.2.1"
     },
     "peerDependencies": {
         "@flareapp/js": "^1.0.0",

packages/react/src/FlareErrorBoundary.ts

@@ -2,6 +2,7 @@ import { flare } from '@flareapp/js';
 import { Component, ErrorInfo, type PropsWithChildren, type ReactNode } from 'react';
 
 import { formatComponentStack } from './format-component-stack';
+import { parseComponentStack } from './parse-component-stack';
 import { FlareReactContext } from './types';
 
 export type FlareErrorBoundaryFallbackProps = {
@@ -36,9 +37,12 @@ export class FlareErrorBoundary extends Component<FlareErrorBoundaryProps, Flare
             errorInfo,
         });
 
+        const rawStack = errorInfo.componentStack ?? '';
+
         const context: FlareReactContext = {
             react: {
-                componentStack: formatComponentStack(errorInfo.componentStack ?? ''),
+                componentStack: formatComponentStack(rawStack),
+                componentStackFrames: parseComponentStack(rawStack),
             },
         };
 

packages/react/src/constants.ts

@@ -0,0 +1,9 @@
+// Chrome:
+// "at ComponentName (http://localhost:5173/src/App.tsx:12:9)"
+// (no source): "at div"
+export const CHROMIUM_STACK_REGEX = /^at\s+(\S+)(?:\s+\((.+):(\d+):(\d+)\))?$/;
+
+// Firefox/Safari:
+// "ComponentName@http://localhost:5173/src/App.tsx:12:9"
+// (no source): "div"
+export const FIREFOX_SAFARI_STACK_REGEX = /^(\S+?)@(.+):(\d+):(\d+)$/;

packages/react/src/flare-react-error-handler.ts

@@ -2,6 +2,7 @@ import { flare } from '@flareapp/js';
 
 import { convertToError } from './convert-to-error';
 import { formatComponentStack } from './format-component-stack';
+import { parseComponentStack } from './parse-component-stack';
 import { FlareReactContext } from './types';
 
 export type FlareReactErrorHandlerCallback = (error: unknown, errorInfo: { componentStack?: string }) => void;
@@ -10,9 +11,12 @@ export function flareReactErrorHandler(callback?: FlareReactErrorHandlerCallback
     return (error: unknown, errorInfo: { componentStack?: string }) => {
         const errorObject = convertToError(error);
 
+        const rawStack = errorInfo.componentStack ?? '';
+
         const context: FlareReactContext = {
             react: {
-                componentStack: formatComponentStack(errorInfo.componentStack ?? ''),
+                componentStack: formatComponentStack(rawStack),
+                componentStackFrames: parseComponentStack(rawStack),
             },
         };
 

packages/react/src/parse-component-stack.ts

@@ -0,0 +1,41 @@
+import { CHROMIUM_STACK_REGEX, FIREFOX_SAFARI_STACK_REGEX } from './constants';
+import { ComponentStackFrame } from './types';
+
+export function parseComponentStack(stack: string): ComponentStackFrame[] {
+    return stack
+        .split(/\s*\n\s*/g)
+        .filter((line) => line.length > 0)
+        .map((line): ComponentStackFrame => {
+            const chromeMatch = line.match(CHROMIUM_STACK_REGEX);
+
+            if (chromeMatch) {
+                return {
+                    component: chromeMatch[1],
+                    file: chromeMatch[2] ?? null,
+                    line: chromeMatch[3] ? Number(chromeMatch[3]) : null,
+                    column: chromeMatch[4] ? Number(chromeMatch[4]) : null,
+                };
+            }
+
+            const firefoxSafariMatch = line.match(FIREFOX_SAFARI_STACK_REGEX);
+
+            if (firefoxSafariMatch) {
+                return {
+                    component: firefoxSafariMatch[1],
+                    file: firefoxSafariMatch[2],
+                    line: Number(firefoxSafariMatch[3]),
+                    column: Number(firefoxSafariMatch[4]),
+                };
+            }
+
+            // For unrecognized formats, we'll strip the leading "at " if it is present
+            const component = line.replace(/^at\s+/, '');
+
+            return {
+                component,
+                file: null,
+                line: null,
+                column: null,
+            };
+        });
+}

packages/react/src/types.ts

@@ -1,5 +1,13 @@
+export type ComponentStackFrame = {
+    component: string;
+    file: string | null;
+    line: number | null;
+    column: number | null;
+};
+
 export type FlareReactContext = {
     react: {
         componentStack: string[];
+        componentStackFrames: ComponentStackFrame[];
     };
 };

packages/react/tests/format-component-stack.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from 'vitest';
+
+import { formatComponentStack } from '../src/format-component-stack';
+
+describe('formatComponentStack', () => {
+    test('splits a component stack into lines', () => {
+        const stack = `
+            at ErrorComponent (http://localhost:5173/src/App.tsx:12:9)
+            at div
+            at App (http://localhost:5173/src/App.tsx:5:3)
+        `;
+
+        expect(formatComponentStack(stack)).toEqual([
+            'at ErrorComponent (http://localhost:5173/src/App.tsx:12:9)',
+            'at div',
+            'at App (http://localhost:5173/src/App.tsx:5:3)',
+        ]);
+    });
+
+    test('returns empty array for empty string', () => {
+        expect(formatComponentStack('')).toEqual([]);
+    });
+
+    test('returns empty array for whitespace-only string', () => {
+        expect(formatComponentStack('   \n   \n   ')).toEqual([]);
+    });
+
+    test('trims whitespace around newlines but not at string edges', () => {
+        const stack = '   at Foo   \n   at Bar   ';
+
+        expect(formatComponentStack(stack)).toEqual(['   at Foo', 'at Bar   ']);
+    });
+
+    test('filters out empty lines between components', () => {
+        const stack = 'at Foo\n\n\nat Bar';
+
+        expect(formatComponentStack(stack)).toEqual(['at Foo', 'at Bar']);
+    });
+
+    test('handles a single-line stack', () => {
+        expect(formatComponentStack('at App')).toEqual(['at App']);
+    });
+});