Faro package that enables easier integration in projects built with React.
Out of the box, the package provides you the following features:
- Error Boundary - Provides additional stacktrace for errors and configuration options for pushError behavior
- Component Profiler - Capture every re-render of a component, the un/mounting time etc.
- Router (v4-v6) integration - Send events for all route changes
- SSR support
To set up Faro-React with React Router V5 or V6 without Data routers, add the following code snippet to your project. If you use React Router V6 with Data Routers, refer to the React Router with Data Routers section.
import { createRoutesFromChildren, matchRoutes, Routes, useLocation, useNavigationType } from 'react-router-dom';
import { getWebInstrumentations, initializeFaro, ReactIntegration, ReactRouterVersion } from '@grafana/faro-react';
import { TracingInstrumentation } from '@grafana/faro-web-tracing';
initializeFaro({
// ...
instrumentations: [
// Load the default Web instrumentations
...getWebInstrumentations(),
// Tracing Instrumentation is needed if you want to use the React Profiler
new TracingInstrumentation(),
new ReactIntegration({
// Only needed if you want to use the React Router instrumentation
router: {
version: ReactRouterVersion.V6,
dependencies: {
createRoutesFromChildren,
matchRoutes,
Routes,
useLocation,
useNavigationType,
},
},
// Or if you use react-router v4/v5
router2: {
version: ReactRouterVersion.V5, // or ReactRouterVersion.V4,
dependencies: {
history, // the history object used by react-router
Route, // Route component imported from react-router package
},
},
}),
],
});
import { matchRoutes } from 'react-router-dom';
import { getWebInstrumentations, initializeFaro, ReactIntegration, ReactRouterVersion } from '@grafana/faro-react';
import { TracingInstrumentation } from '@grafana/faro-web-tracing';
initializeFaro({
// ...
instrumentations: [
// Load the default Web instrumentations
...getWebInstrumentations(),
// Tracing Instrumentation is needed if you want to use the React Profiler
new TracingInstrumentation(),
new ReactIntegration({
// Only needed if you want to use the React Router instrumentation
router: {
version: ReactRouterVersion.V6_data_router,
dependencies: {
matchRoutes,
},
},
}),
],
});
// To instrument the router you need to attach Faro instrumentations providing it to the withFaroRouterInstrumentation function
// Do this in your App.js or other file where you create the router.
const reactBrowserRouter = createBrowserRouter([
//...
]);
const browserRouter = withFaroRouterInstrumentation(reactBrowserRouter);
import { FaroErrorBoundary } from '@grafana/faro-react';
// during render
<FaroErrorBoundary>
<App />
</FaroErrorBoundary>;
or
import { withErrorBoundary } from '@grafana/faro-react';
export default withErrorBoundary(App);
import { FaroErrorBoundary, PushErrorOptions } from '@grafana/faro-react';
const pushErrorOptions: PushErrorOptions = {
type: "Custom Error Type"
context: {
foo: "bar",
baz: "qux"
},
// ...
}
// during render
<FaroErrorBoundary pushErrorOptions={pushErrorOptions}>
<App />
</FaroErrorBoundary>;
import { FaroRoutes } from '@grafana/faro-react';
// during render
<FaroRoutes>
<Route path="/" element={<Home />} />
{/* ... */}
</FaroRoutes>;
- Create a data router (createBrowserRouter, createHashRouter, createMemoryRouter)
- Instrument the data router to receive route changes by wrapping it with
withFaroRouterInstrumentation()
const reactBrowserRouter = createBrowserRouter([
//...
]);
const browserRouter = withFaroRouterInstrumentation(reactBrowserRouter);
import { FaroRoute } from '@grafana/faro-react';
// during render
<Switch>
<FaroRoute path="/">
<Home />
</FaroRoute>
{/* ... */}
</Switch>;
- Change
version
property fromReactRouterVersion.V6
toReactRouterVersion.V6_data_router
. - Remove the following dependencies from the dependencies object
createRoutesFromChildren
Routes
useLocation
useNavigationType
Example: updating dependencies
initializeFaro({
// ...
instrumentations: [
// Load the default Web instrumentations
...getWebInstrumentations(),
// Tracing Instrumentation is needed if you want to use the React Profiler
new TracingInstrumentation(),
new ReactIntegration({
// Only needed if you want to use the React Router instrumentation
router: {
// version: ReactRouterVersion.V6 // => change to .V6_data_router,
version: ReactRouterVersion.V6_data_router,
dependencies: {
matchRoutes,
// +++ remove the following dependencies +++
// createRoutesFromChildren,
// Routes,
// useLocation,
// useNavigationType,
},
},
}),
],
});
- Remove
<FaroRoutes>
component. This will not work anymore with V6 data routers. - Create a data router and wrap it with
withFaroRouterInstrumentation(dataRouter)
Example: Instrument Router
const reactBrowserRouter = createBrowserRouter([
// your routes
]);
const browserRouter = withFaroRouterInstrumentation(reactBrowserRouter);
import { withFaroProfiler } from '@grafana/faro-react';
export default withFaroProfiler(App);