@browsonic/react

React adapter for @browsonic/sdk. Catches the render errors that window.onerror cannot see.

React's reconciler swallows render-time exceptions and shows a fallback tree — the error never bubbles to window, so a plain @browsonic/sdk install reports nothing. This adapter wires React's Error Boundary primitive to Browsonic so those errors get reported, with the React component stack attached.

npm install @browsonic/sdk @browsonic/react

import { Browsonic } from '@browsonic/sdk';
import { BrowsonicErrorBoundary } from '@browsonic/react';

const sdk = new Browsonic();
sdk.init({
  apiEndpoint: 'https://your-ingest.example.com',
  appKey: 'your-app-key',
});

function App() {
  return (
    <BrowsonicErrorBoundary
      sdk={sdk}
      fallback={(error, reset) => (
        <div role="alert">
          <p>Something went wrong: {error.message}</p>
          <button onClick={reset}>Try again</button>
        </div>
      )}
    >
      <YourApp />
    </BrowsonicErrorBoundary>
  );
}

What this adapter ships

Shipped in 0.1:

• <BrowsonicErrorBoundary> — render-time error capture with reset support and Suspense-safe fallbacks.
• useBrowsonic() — singleton instance hook (lazy at mount, stable for the lifetime of the component).
• useUser(user | null) — sets / clears user context as the component mounts and updates when the user fields change.
• useCaptureError() — stable callback for try/catch sites and event handlers.
• withBrowsonic(Component) — HOC that injects sdk as a prop, for class components that cannot consume hooks.

Deferred to 0.2 / 0.3 (see ROADMAP.md):

• React Router v6 / v7 instrumentation — automatic page-view events on route change.

import { BrowsonicErrorBoundary, useBrowsonic, useUser, useCaptureError } from '@browsonic/react';

function App({ currentUser }) {
  // Set user context for every event captured while this component is mounted.
  useUser(currentUser); // pass `null` to clear

  return (
    <BrowsonicErrorBoundary fallback={<ErrorScreen />}>
      <Checkout />
    </BrowsonicErrorBoundary>
  );
}

function Checkout() {
  const captureError = useCaptureError();
  const sdk = useBrowsonic();

  const buy = async () => {
    try {
      await api.buy();
    } catch (err) {
      // Event handlers don't reach Error Boundaries — capture manually.
      captureError(err as Error);
    }
  };

  return <button onClick={buy}>Buy</button>;
}

The package follows the @browsonic/sdk release cadence; SemVer strict.

Compatibility

| Surface | Versions | | ----------------- | ---------- | | React | 18.x, 19.x | | @browsonic/sdk | ≥ 2.2.1 | | Node (build/test) | ≥ 20 |

Privacy

The adapter does not collect data on its own — it forwards to the SDK, which carries Browsonic's privacy-first defaults. See PRIVACY.md in the SDK repo.

The adapter attaches a truncated React component stack (≤ 1024 chars) as event metadata when reporting a render error. This is React's own componentStack string — the same one React already shows in dev console — and never includes prop or state values.

License

Apache License 2.0 — see LICENSE and NOTICE.