React ErrorBoundary support

In React error boundaries are components that allow you to render a fallback UI in case an error occurs in the respective React component tree.

Faro provides its own error boundary component which enhances the standard React error boundary with Faro specific functionality.

In case of an error it sends a Faro error event which contains the error message, the React component stack of the component which contains the exception, and the name of name of the error boundary if configured.

import { getWebInstrumentations, initializeFaro, ReactIntegration } from '@grafana/faro-react';

initializeFaro({
  // ...

  instrumentations: [
    // Load the default Web instrumentations
    ...getWebInstrumentations(),

    // minimum setup to get the FaroErrorBoundary support
    new ReactIntegration(),
  ],
});

import { FaroErrorBoundary } from '@grafana/faro-react';

// during render
<FaroErrorBoundary>
  <App />
</FaroErrorBoundary>;

import { withErrorBoundary } from '@grafana/faro-react';

export default withErrorBoundary(App);

FaroErrorBoundary properties

Configuration options:

fallback: The fallback UI to render instead, either:
- a ReactElement
- FaroErrorBoundaryFallbackRender function that passes the Error object and a callback function to reset the error boundary to it’s initial state when called
pushErrorOptions: Options passed to the pushError API, for example additional context to an error

Lifecycle callbacks:

beforeCapture: Executed before the Faro pushError API call, with the Error object as a parameter
onError: Executed when an error occurs, with the Error object as a parameter
onMount: Executed when React calls the componentDidMount lifecycle hook
onUnmount: Executed when React calls the componentWillUnmount lifecycle hook, with the Error object as a parameter
onReset: Executed when React calls resetErrorBoundary, with the Error object as a parameter

import { FaroErrorBoundary, PushErrorOptions } from '@grafana/faro-react';

const pushErrorOptions: PushErrorOptions = {
  type: "Custom Error Type"
  context: {
    foo: "bar",
    baz: "abc"
  },
};

// during render
<FaroErrorBoundary
  beforeCapture={(error) => handleBeforeCapture(error)}
  onError={(error) => handleError(error)}
  onMount={() => handleOnMount()}
  onUnmount={(error) => handleUnmount(error)}
  onReset={(error) => handleReset(error)}
  pushErrorOptions={pushErrorOptions}
  fallback={(error, resetBoundary) => {
    return errorBoundaryFallbackRenderer(error, resetBoundary) }}
 >
  <App />
</FaroErrorBoundary>;