Quickstart setup for Faro-React and Frontend Observability

Follow these steps to get started quickly with the Faro-React Web SDK for React Router v6 with data router and Grafana Cloud Frontend Observability:

Install the Faro-React Web SDK
Instrument your application
Create an Frontend Observability application
Observe the application in Frontend Observability

The Faro Web SDK is a highly configurable open source real user monitoring (RUM) library built on OpenTelemetry and integrating seamlessly with Grafana Cloud and Grafana Frontend Observability.

Faro-React is a distribution of the Faro Web SDK for project using React, which offers easier integrations and the following features:

Support for React Router v6 or v4/v5.x: send events for all route changes, including the data router API
Error boundary: enhancements to stack traces and configuration options for pushError behavior
Component profiler: to capture component renders, un/mounting time, and more
SSR support server side rendering support for React

This document covers setting up Faro-React with React Router v6 with or without the data router API, and v4/v5.x.

If you use React Router v4 or v5, or want to use React Router v6 without the data router, refer to the React instrumentation documentation.

To upgrade your project to React Router v6 with a data router, refer to the Upgrade to a data router section of the documentation.

Install the Faro-React Web SDK

First add Faro-React to your project. Install the Faro-React package by running the following command for NPM:

# install globally
npm i @grafana/faro-react

Or the following command Yarn:

yarn add @grafana/faro-react

The Faro-React package offers all the functionality and behavior from the Faro Web SDK package plus additional React specific functionality like router instrumentation, a custom ErrorBoundary, and more.

Add the following code snippet to your project to import Faro-React with the minimum setup needed to get insights into the health and performance of your application or website:

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

initializeFaro({
  // required: the URL of the Grafana collector
  url: 'my/collector/url',

  // required: the identification label of your application
  app: {
    name: 'my-react-app',
  },
});

Faro-React captures data about your application’s health and performance and exports them to the Grafana Cloud faro receiver.

Open source users can use the Grafana Alloy as their data collector, to learn more consult the Faro receiver with Grafana Alloy documentation.

Instrument your application

Next, instrument the routes from a React data router (BrowserRouter, HashRouter, or MemoryRouter).

In the file you create your data router, often the App.\* file pass your data router to the Faro-React function withFaroRouterInstrumentation to wrap all your routes with Faro instrumentation:

const reactBrowserRouter = createBrowserRouter([
  // your routes...
]);

const browserRouter = withFaroRouterInstrumentation(reactBrowserRouter);

Create an Frontend Observability application

To observe Real User Monitoring (RUM) data in Grafana Cloud Frontend Observability create an application in the Grafana Cloud Frontend Observability plugin:

Sign in to Grafana Cloud, register for a Free Grafana Cloud account if required, to get to the Grafana Cloud Portal page [https://grafana.com/profile/org].
If the account has access to multiple Grafana Cloud Organizations, select an organization from the top left organization drop-down.
If the organization has access to multiple Grafana Cloud Stacks, navigate to a stack from the left side bar or the main Stacks list.
With a stack selected, or in the single stack scenario, below Manage your Grafana Cloud Stack, click Launch in the Grafana section:
Use the left navigation to expand Frontend and select Frontend Apps.
If this is the first time you access Frontend Observability it will display the landing page. Click Start observing on the landing page to navigate to the overview page.
From the overview page, click Create new and to create a Frontend Observability application to hold RUM data for your web application.
To create an application requires the following information:
- App Name: Give your app a meaningful name
- CORS Allowed Origin: Domains allowed to access your Frontend Observability application, for local development set the value to localhost
- Default attributes: Any attributed you’d like added to all signals, if unknown leave empty
Connect your instrumentation to Frontend Observability, from the Web SDK Configuration tab, copy the url value and add it to your instrumentation script to tell Faro which application to send data to. Make use of the CORS domain to secure your Frontend Observability application to specific domains.