Merge pull request #18 from spatie/feature/react-flare-error-boundary-on-error-callback

Setup alias for playground development and add onError callback

Author: sebastienhenau

.claude/docs/react-improvements.md

@@ -0,0 +1,99 @@
+# Research: Improving `@flareapp/react` Context Collection
+
+## Current State
+
+The `FlareErrorBoundary` currently captures:
+
+- The error object
+- `componentStack` string from React's `ErrorInfo` (formatted)
+- Standard browser context via `@flareapp/js` (URL, user agent, cookies, query params)
+
+That's about it. There's room to grow.
+
+---
+
+## Industry Landscape
+
+| Feature                        | Industry standard | Flare   |
+|--------------------------------|-------------------|---------|
+| Component stack                | Yes               | Yes     |
+| Component names in breadcrumbs | Some (via plugins)| No      |
+| Component props/state          | **No**            | **No**  |
+| Redux/store state              | Some              | No      |
+| React Router integration       | Some              | No      |
+| React 19 root error handlers   | Emerging          | No      |
+| Component interaction trail    | Rare              | No      |
+| `beforeCapture` scope hook     | Rare              | No      |
+| User feedback dialog           | Rare              | No      |
+| Component profiling            | Rare              | No      |
+
+**Key finding: Nobody automatically captures component props or state.** Despite the theoretical possibility via React
+fiber internals, every tool either ignores these or provides manual hooks. Reasons: serialization complexity (circular
+refs, functions, React elements), performance cost of fiber tree traversal, and privacy risks (leaking PII/tokens).
+
+---
+
+## What's Worth Implementing (Prioritized)
+
+### Tier 1 -- Baseline improvements (low effort, high value)
+
+1. **Better component stack formatting and sourcemap-decoded display** -- currently just splitting by newline. Could
+   parse into structured data (component name, file, line) for better Flare dashboard rendering.
+
+2. **`beforeCapture` callback on ErrorBoundary** -- a `beforeCapture(scope, error, componentStack)` hook. Lets
+   users attach custom tags, component props, or state to the error before it's sent. This is the pragmatic answer to "
+   how do we capture state" -- let the developer decide what to include.
+
+3. **React 19 `createRoot` error handlers** -- provide a `flareReactErrorHandler()` function for the new
+   `onCaughtError`/`onUncaughtError`/`onRecoverableError` hooks. Few tools support this today. Gets you
+   error capture *without* requiring an ErrorBoundary wrapper.
+
+### Tier 2 -- Differentiating features (moderate effort)
+
+4. **Component name annotation via build plugin** -- inject component name and source file attributes onto DOM nodes at
+   build time (e.g. `data-flare-component`, `data-flare-source-file`). These survive minification. Since Flare already
+   has `@flareapp/vite`, this could be a Vite plugin addition or a separate Babel plugin. Component names would then
+   appear in breadcrumbs/glows.
+
+5. **React Router integration** -- capture parameterized route names (`/users/:id` instead of `/users/12345`) as
+   context. Add navigation breadcrumbs on route changes. Support React Router v6/v7 and TanStack Router.
+
+6. **State management integration** -- provide a Redux middleware and/or Zustand middleware that attaches store state
+   snapshots to error reports. Use a `stateTransformer` for sanitization.
+   This is where "capture state" actually becomes practical -- at the store level, not the component level.
+
+### Tier 3 -- Nice-to-have (higher effort)
+
+7. **Component interaction breadcrumbs** -- track which components the user interacted with before the error. This gives
+   a "user journey through components" trail.
+
+8. **Component profiling** -- `withProfiler()` HOC / `useProfiler()` hook that tracks mount/render/update timing. Useful
+   for correlating errors with performance, but requires a tracing infrastructure.
+
+---
+
+## What's NOT Worth Pursuing
+
+- **Automatic props/state via fiber internals** -- no tool does this reliably. Internal API instability across React
+  versions, serialization nightmares, privacy risks, performance cost. The fiber tree (`memoizedProps`, `memoizedState`)
+  is unstable and undocumented.
+- **`captureOwnerStack()`** -- React 19 API that returns `null` in production. Development-only, useless for error
+  tracking.
+- **Session replay** -- massive scope, framework-agnostic, not a React package concern.
+
+---
+
+## Recommended Implementation Order
+
+For the `@flareapp/react` package specifically:
+
+1. `beforeCapture` callback on `FlareErrorBoundary` -- quick win, gives users control
+2. React 19 `createRoot` error handler utility -- forward-looking, few tools support this yet
+3. Structured component stack parsing -- better data for the Flare dashboard
+4. Vite/Babel plugin for component name annotations -- builds on existing `@flareapp/vite`
+5. React Router integration (v6/v7)
+6. Redux/Zustand middleware (could be separate packages)
+
+## Tasks
+
+- [x] FlareErrorBoundary supports onError callback

package.json

@@ -11,7 +11,7 @@
         "build": "npm run build --workspaces --if-present",
         "test": "npm run test --workspaces --if-present",
         "typescript": "npm run typescript --workspaces --if-present",
-        "playground": "npm run build && npm run dev --workspace=playground",
+        "playground": "npm run dev --workspace=playground",
         "format": "prettier --write \"**/*.{js,json,vue,ts,tsx}\"",
         "prepare": "husky"
     },

packages/js/src/env/index.ts

@@ -3,7 +3,9 @@ declare const FLARE_SOURCEMAP_VERSION: string | undefined;
 
 // Injected during build
 export const CLIENT_VERSION =
-    typeof process.env.FLARE_JS_CLIENT_VERSION === 'undefined' ? '?' : process.env.FLARE_JS_CLIENT_VERSION;
+    typeof process !== 'undefined' && typeof process.env?.FLARE_JS_CLIENT_VERSION !== 'undefined'
+        ? process.env.FLARE_JS_CLIENT_VERSION
+        : '?';
 
 // Injected by flare-vite-plugin-sourcemap-uploader (optional)
 export const KEY = typeof FLARE_JS_KEY === 'undefined' ? '' : FLARE_JS_KEY;

packages/react/src/FlareErrorBoundary.ts

@@ -0,0 +1,28 @@
+import { flare } from '@flareapp/js';
+import { Component, ErrorInfo, type PropsWithChildren, type ReactNode } from 'react';
+
+import { formatComponentStack } from './format-component-stack';
+
+type Props = PropsWithChildren<{
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+}>;
+
+type State = {};
+
+export class FlareErrorBoundary extends Component<Props, State> {
+    componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+        const context = {
+            react: {
+                componentStack: formatComponentStack(errorInfo.componentStack ?? ''),
+            },
+        };
+
+        flare.report(error, context, { react: { errorInfo } });
+
+        this.props.onError?.(error, errorInfo);
+    }
+
+    render(): ReactNode {
+        return this.props.children;
+    }
+}

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

@@ -0,0 +1,3 @@
+export function formatComponentStack(stack: string): string[] {
+    return stack.split(/\s*\n\s*/g).filter((line) => line.length > 0);
+}

packages/react/src/index.ts

@@ -1,28 +1 @@
-import { flare } from '@flareapp/js';
-import { Component, PropsWithChildren } from 'react';
-
-interface Context {
-    react: {
-        componentStack: Array<String>;
-    };
-}
-
-export class FlareErrorBoundary extends Component<PropsWithChildren> {
-    componentDidCatch(error: Error, reactErrorInfo: React.ErrorInfo) {
-        const context: Context = {
-            react: {
-                componentStack: formatReactComponentStack(reactErrorInfo?.componentStack ?? ''),
-            },
-        };
-
-        flare.report(error, context, { react: { errorInfo: reactErrorInfo } });
-    }
-
-    render() {
-        return this.props.children;
-    }
-}
-
-function formatReactComponentStack(stack: string) {
-    return stack.split(/\s*\n\s*/g).filter((line) => line.length > 0);
-}
+export { FlareErrorBoundary } from './FlareErrorBoundary';

playground/react/App.tsx

@@ -28,7 +28,7 @@ export function App() {
                 Reset render error
             </Button>
             {showBuggy && (
-                <FlareErrorBoundary>
+                <FlareErrorBoundary onError={() => console.log('FlareErrorBoundary onError callback')}>
                     <BuggyComponent />
                 </FlareErrorBoundary>
             )}

playground/tsconfig.json

@@ -1,7 +1,12 @@
 {
     "extends": "../tsconfig.json",
     "compilerOptions": {
-        "jsx": "react-jsx"
+        "jsx": "react-jsx",
+        "paths": {
+            "@flareapp/js": ["../packages/js/src/index.ts"],
+            "@flareapp/react": ["../packages/react/src/index.ts"],
+            "@flareapp/vue": ["../packages/vue/src/index.ts"]
+        }
     },
     "include": ["**/*.ts", "**/*.tsx", "**/*.vue"]
 }

playground/vite.config.ts

@@ -9,6 +9,13 @@ export default defineConfig(({ mode }) => {
     const env = loadEnv(mode, process.cwd());
 
     return {
+        resolve: {
+            alias: {
+                '@flareapp/js': resolve(__dirname, '../packages/js/src/index.ts'),
+                '@flareapp/react': resolve(__dirname, '../packages/react/src/index.ts'),
+                '@flareapp/vue': resolve(__dirname, '../packages/vue/src/index.ts'),
+            },
+        },
         plugins: [
             tailwindcss(),
             react(),