Merge pull request #28 from spatie/feature/react-improvements

Feature/react improvements

Author: sebastienhenau

.claude/CLAUDE.md

@@ -7,6 +7,7 @@
 - We're equals.
 - Try to be neutral and objective.
 - Do not use emojis.
+- Do not use -- when writing comments or explaining something.
 - For more information regarding:
     - The research: take a look at .claude/docs/research
     - Repo cleanup: take a look at .claude/docs/repo-cleanup

…de/docs/projects - react-improvements.md …aude/docs/projects-react-improvements.md.claude/docs/projects - react-improvements.md renamed to .claude/docs/projects-react-improvements.md .claude/docs/projects - react-improvements.md renamed to .claude/docs/projects-react-improvements.md

@@ -5,12 +5,13 @@
 - [x] FlareErrorBoundary supports `fallback` property
 - [x] FlareErrorBoundary supports fallback with a reset method for resetting the Error Boundary
 - [x] FlareErrorBoundary fallback passes `componentStack`
-- [x] FlareErrorBoundary supports `onError` callback
-- [x] FlareErrorBoundary supports `beforeCapture` callback
+- [x] FlareErrorBoundary supports `beforeEvaluate` callback
+- [x] FlareErrorBoundary supports `beforeSubmit` callback
+- [x] FlareErrorBoundary supports `afterSubmit` callback
 - [x] FlareErrorBoundary supports `onReset` property
 - [x] FlareErrorBoundary `onReset` passes previous error
 - [x] FlareErrorBoundary supports `resetKeys` property
-- [x] Add `flareReactErrorHandler`
+- [x] Add `flareReactErrorHandler` with `beforeEvaluate`, `beforeSubmit`, and `afterSubmit` callbacks
 - [x] Structured component stack parsing with sourcemap-ready frames
 
 ## FlareErrorBoundary: `fallback` property
@@ -47,37 +48,64 @@ The `fallback` prop accepts either a static `ReactNode` or a render function. Th
 </FlareErrorBoundary>
 ```
 
-## FlareErrorBoundary: `onError` callback
+## FlareErrorBoundary: `beforeEvaluate` callback
 
 ### Why
 
-Developers need a hook to perform side effects when an error is caught -- logging to a secondary service,
-showing a toast, updating app state, etc. This fires *after* the error has been reported to Flare.
+Fires *before* the component stack context is built, giving developers a chance to attach custom context, tags, or
+user information to the Flare report. This is the pragmatic answer to "how do we capture component props/state" -- let
+the developer decide what to include rather than trying to automatically serialize React internals.
 
 ```tsx
 <FlareErrorBoundary
-    onError={({ error, errorInfo }) => {
-        console.error('Caught by FlareErrorBoundary:', error);
-        console.error('Component stack:', errorInfo.componentStack);
+    beforeEvaluate={({ error, errorInfo }) => {
+        flare.addContext('user', { id: currentUser.id });
+        flare.addContext('feature-flags', getActiveFlags());
     }}
 >
     <App />
 </FlareErrorBoundary>
 ```
 
-## FlareErrorBoundary: `beforeCapture` callback
+## FlareErrorBoundary: `beforeSubmit` callback
 
 ### Why
 
-Fires *before* the error is reported to Flare, giving developers a chance to attach custom context, tags, or
-user information to the Flare report. This is the pragmatic answer to "how do we capture component props/state" -- let
-the developer decide what to include rather than trying to automatically serialize React internals.
+Fires after the component stack context is built but *before* the error is reported to Flare. The callback receives
+the `context` and must return a (possibly modified) context object. Use this to filter or enrich the report context.
 
 ```tsx
 <FlareErrorBoundary
-    beforeCapture={({ error, errorInfo }) => {
-        flare.addContext('user', { id: currentUser.id });
-        flare.addContext('feature-flags', getActiveFlags());
+    beforeSubmit={({ error, errorInfo, context }) => {
+        return {
+            ...context,
+            react: {
+                ...context.react,
+                componentStack: context.react.componentStack.filter(
+                    (line) => !line.includes('ThirdPartyWrapper'),
+                ),
+            },
+        };
+    }}
+>
+    <App />
+</FlareErrorBoundary>
+```
+
+## FlareErrorBoundary: `afterSubmit` callback
+
+### Why
+
+Developers need a hook to perform side effects when an error is caught -- logging to a secondary service,
+showing a toast, updating app state, etc. This fires *after* the error has been reported to Flare. The callback
+receives the final context that was submitted.
+
+```tsx
+<FlareErrorBoundary
+    afterSubmit={({ error, errorInfo, context }) => {
+        console.error('Caught by FlareErrorBoundary:', error);
+        console.error('Component stack:', errorInfo.componentStack);
+        console.error('Reported context:', context);
     }}
 >
     <App />
@@ -142,22 +170,37 @@ function App() {
 React 19 introduced `onCaughtError`, `onUncaughtError`, and `onRecoverableError` callbacks on `createRoot`.
 These are root-level error handlers that catch errors *without* requiring an ErrorBoundary wrapper.
 
-`flareReactErrorHandler` is a wrapper function that accepts an optional callback. It also handles non-Error values
-(strings, objects) by converting them to proper Error instances via `convertToError()`, making it more resilient to
-edge cases.
+`flareReactErrorHandler` is a wrapper function that accepts an optional options object with `beforeEvaluate`,
+`beforeSubmit`, and `afterSubmit` callbacks -- the same callback pattern used by `FlareErrorBoundary`. It also handles
+non-Error values (strings, objects) by converting them to proper Error instances via `convertToError()`, making it more
+resilient to edge cases.
+
+### Callback lifecycle
+
+1. **`beforeEvaluate`** -- called after the error is converted to an `Error`, before building the component stack context. Use this to attach custom context to Flare (e.g. user info, feature flags).
+2. **`beforeSubmit`** -- called with the built context, must return a (possibly modified) context object. Use this to filter or enrich the report context before it is sent.
+3. **`flare.report()`** -- the error is reported to Flare.
+4. **`afterSubmit`** -- called after the report is sent. Use this for side effects like logging or showing a toast.
 
 ```tsx
 import { flareReactErrorHandler } from '@flareapp/react';
 
 const root = createRoot(document.getElementById('root')!, {
     // Errors caught by an Error Boundary
-    onCaughtError: flareReactErrorHandler((error, errorInfo) => {
-        console.warn('Caught error:', error);
+    onCaughtError: flareReactErrorHandler({
+        afterSubmit: ({ error, errorInfo }) => {
+            console.warn('Caught error:', error);
+        },
     }),
 
     // Errors NOT caught by any Error Boundary
-    onUncaughtError: flareReactErrorHandler((error, errorInfo) => {
-        console.error('Uncaught error:', error);
+    onUncaughtError: flareReactErrorHandler({
+        beforeEvaluate: ({ error }) => {
+            flare.addContext('user', { id: currentUser.id });
+        },
+        afterSubmit: ({ error }) => {
+            console.error('Uncaught error:', error);
+        },
     }),
 
     // Errors React recovers from automatically (e.g. hydration mismatches)

.claude/docs/research.md

@@ -63,7 +63,7 @@ handling (strings, numbers silently dropped).
 `sendBeacon()` for unload, no request timeout.
 
 **React** (`@flareapp/react`) — captures component stack string only. Missing: fallback UI (`getDerivedStateFromError`),
-component props, component name, onError/onReset callbacks, React Router integration, state management integration.
+component props, component name, afterSubmit/onReset callbacks, React Router integration, state management integration.
 
 **Vue** (`@flareapp/vue`) — captures component name + info string. Missing: component props, Vue Router context,
 Pinia/Vuex state, component tree.
@@ -123,7 +123,7 @@ Sprint target: fallback UI, callbacks, and component name. Defer React Router in
 - [ ] Fallback UI: implement `getDerivedStateFromError` so the boundary can render a fallback component
 - [ ] Configurable fallback: `<FlareErrorBoundary fallback={<ErrorPage />}>` or render prop
   `fallback={(error, reset) => ...}`
-- [ ] `onError` callback prop: let developers hook into error events
+- [ ] `afterSubmit` callback prop: let developers hook into error events
 - [ ] `onReset` callback prop: for error recovery flows
 - [ ] Capture component props from the error boundary's child tree
 - [ ] Capture the erroring component's name (not just the stack)

packages/react/src/FlareErrorBoundary.ts

@@ -1,8 +1,8 @@
 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 { formatComponentStack } from './formatComponentStack';
+import { parseComponentStack } from './parseComponentStack';
 import { FlareReactContext } from './types';
 
 export type FlareErrorBoundaryFallbackProps = {
@@ -14,8 +14,9 @@ export type FlareErrorBoundaryFallbackProps = {
 export type FlareErrorBoundaryProps = PropsWithChildren<{
     fallback?: ReactNode | ((props: FlareErrorBoundaryFallbackProps) => ReactNode);
     resetKeys?: unknown[];
-    beforeCapture?: (params: { error: Error; errorInfo: ErrorInfo }) => void;
-    onError?: (params: { error: Error; errorInfo: ErrorInfo }) => void;
+    beforeEvaluate?: (params: { error: Error; errorInfo: ErrorInfo }) => void;
+    beforeSubmit?: (params: { error: Error; errorInfo: ErrorInfo; context: FlareReactContext }) => FlareReactContext;
+    afterSubmit?: (params: { error: Error; errorInfo: ErrorInfo; context: FlareReactContext }) => void;
     onReset?: (error: Error | null) => void;
 }>;
 
@@ -32,7 +33,7 @@ export class FlareErrorBoundary extends Component<FlareErrorBoundaryProps, Flare
     }
 
     componentDidCatch(error: Error, errorInfo: ErrorInfo) {
-        this.props.beforeCapture?.({
+        this.props.beforeEvaluate?.({
             error,
             errorInfo,
         });
@@ -46,13 +47,21 @@ export class FlareErrorBoundary extends Component<FlareErrorBoundaryProps, Flare
             },
         };
 
-        this.setState({ componentStack: context.react.componentStack });
+        const finalContext =
+            this.props.beforeSubmit?.({
+                error,
+                errorInfo,
+                context,
+            }) ?? context;
 
-        flare.report(error, context, { react: { errorInfo } });
+        this.setState({ componentStack: finalContext.react.componentStack });
 
-        this.props.onError?.({
+        flare.report(error, finalContext, { react: { errorInfo } });
+
+        this.props.afterSubmit?.({
             error,
             errorInfo,
+            context: finalContext,
         });
     }
 

packages/react/src/convert-to-error.ts packages/react/src/convertToError.tspackages/react/src/convert-to-error.ts renamed to packages/react/src/convertToError.ts

@@ -0,0 +1,50 @@
+import { flare } from '@flareapp/js';
+
+import { convertToError } from './convertToError';
+import { formatComponentStack } from './formatComponentStack';
+import { parseComponentStack } from './parseComponentStack';
+import { FlareReactContext } from './types';
+
+export type FlareReactErrorHandlerCallback = (error: unknown, errorInfo: { componentStack?: string }) => void;
+
+export type FlareReactErrorHandlerOptions = {
+    beforeEvaluate?: (params: { error: Error; errorInfo: { componentStack?: string } }) => void;
+    beforeSubmit?: (params: {
+        error: Error;
+        errorInfo: { componentStack?: string };
+        context: FlareReactContext;
+    }) => FlareReactContext;
+    afterSubmit?: (params: {
+        error: Error;
+        errorInfo: { componentStack?: string };
+        context: FlareReactContext;
+    }) => void;
+};
+
+export function flareReactErrorHandler(options?: FlareReactErrorHandlerOptions): FlareReactErrorHandlerCallback {
+    return (error: unknown, errorInfo: { componentStack?: string }) => {
+        const errorObject = convertToError(error);
+
+        options?.beforeEvaluate?.({ error: errorObject, errorInfo });
+
+        const rawStack = errorInfo.componentStack ?? '';
+
+        const context: FlareReactContext = {
+            react: {
+                componentStack: formatComponentStack(rawStack),
+                componentStackFrames: parseComponentStack(rawStack),
+            },
+        };
+
+        const finalContext =
+            options?.beforeSubmit?.({
+                error: errorObject,
+                errorInfo,
+                context,
+            }) ?? context;
+
+        flare.report(errorObject, finalContext, { react: { errorInfo } });
+
+        options?.afterSubmit?.({ error: errorObject, errorInfo, context: finalContext });
+    };
+}

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

@@ -5,4 +5,8 @@ export {
     type FlareErrorBoundaryState,
 } from './FlareErrorBoundary';
 
-export { flareReactErrorHandler, type FlareReactErrorHandlerCallback } from './flare-react-error-handler';
+export {
+    flareReactErrorHandler,
+    type FlareReactErrorHandlerCallback,
+    type FlareReactErrorHandlerOptions,
+} from './flareReactErrorHandler';