Documentation Grafana Cloud Monitor applications Frontend Observability Instrument React ErrorBoundary support

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.

ts Copy

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(),
  ],
});

tsx Copy

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

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

or

tsx Copy

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

tsx Copy

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>;