@grafana/faro-react 2.0.0-beta-2 → 2.1.0

package/README.md

@@ -6,9 +6,8 @@ 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
+- Component Profiler - Capture every re-render of a component, the un/mounting time etc
+- Router (v4–v7) integration - Send events for all route changes.
 
 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.
@@ -16,413 +15,12 @@ OpenTelemetry and integrating seamlessly with Grafana Cloud and Grafana Frontend
 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
+- **Support for React Router v4–v7**: 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
-- **Server side rendering (SSR) support**
+- **Component profiler**: to capture component renders, un/mounting time, and more.
 
-## Install the Faro-React Web SDK
+## How to instrument with Faro React
 
-First add Faro-React to your project. Install the Faro-React package by running the following command
-for NPM:
-
-```sh
-npm i @grafana/faro-react
-```
-
-Or with Yarn:
-
-```sh
-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:
-
-```ts
-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
-configured collector like Grafana Alloy.
-
-## Instrument your application
-
-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.
-
-### Router v6 with Data Router
-
-```ts
-import {
-  initializeFaro,
-  createReactRouterV6DataOptions,
-  ReactIntegration,
-  getWebInstrumentations,
-} from '@grafana/faro-react';
-
-import { matchRoutes } from 'react-router-dom';
-
-initializeFaro({
-  // ...
-
-  instrumentations: [
-    // Load the default Web instrumentations
-    ...getWebInstrumentations(),
-
-    new ReactIntegration({
-      router: createReactRouterV6DataOptions({
-        matchRoutes,
-      }),
-    }),
-  ],
-});
-```
-
-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 and apply Faro auto instrumentation:
-
-```ts
-import { createBrowserRouter } from 'react-router-dom';
-
-const reactBrowserRouter = createBrowserRouter([
-  // your routes...
-]);
-
-const browserRouter = withFaroRouterInstrumentation(reactBrowserRouter);
-```
-
-### Router v6 (no Data Router)
-
-In the file you define your router, import `createRoutesFromChildren`, `matchRoutes`, `Routes`,
-`useLocation`, `useNavigationType` from `react-router-dom` and pass them to the dependencies object.
-
-```ts
-import { createRoutesFromChildren, matchRoutes, Routes, useLocation, useNavigationType } from 'react-router-dom';
-
-import {
-  createReactRouterV6Options,
-  getWebInstrumentations,
-  initializeFaro,
-  ReactIntegration,
-  ReactRouterVersion,
-} from '@grafana/faro-react';
-
-initializeFaro({
-  // Mandatory, the URL of the Grafana collector
-  url: 'my/collector/url',
-
-  // Mandatory, the identification label of your application
-  app: {
-    name: 'my-react-app',
-  },
-
-  // ...
-
-  instrumentations: [
-    // Load the default Web instrumentations
-    ...getWebInstrumentations(),
-
-    new ReactIntegration({
-      router: createReactRouterV6Options({
-        createRoutesFromChildren,
-        matchRoutes,
-        Routes,
-        useLocation,
-        useNavigationType,
-      }),
-    }),
-  ],
-});
-```
-
-To instrument React Router v6 import the `<FaroRoutes/>` component and use it instead of the React
-router `<Routes />` component, for example:
-
-```tsx
-import { FaroRoutes } from '@grafana/faro-react';
-
-// during render
-<FaroRoutes>
-  <Route path="/" element={<Home />} />
-  {/* ... */}
-</FaroRoutes>;
-```
-
-### Router v4/v5
-
-To instrument React Router v4 or v5, import the `Route` component from `react-router-dom` and the
-`history` object from the `history package` and pass them to the dependencies object:
-
-The final result should look similar like this example:
-
-```ts
-import { createBrowserHistory } from 'history';
-import { Route } from 'react-router-dom';
-
-import {
-  // or createReactRouterV4Options
-  createReactRouterV5Options,
-  getWebInstrumentations,
-  initializeFaro,
-  ReactIntegration,
-  ReactRouterVersion,
-} from '@grafana/faro-react';
-
-const history = createBrowserHistory();
-
-initializeFaro({
-  // Mandatory, the URL of the Grafana collector
-  url: 'my/collector/url',
-
-  // Mandatory, the identification label of your application
-  app: {
-    name: 'my-react-app',
-  },
-
-  // ...
-
-  instrumentations: [
-    // Load the default Web instrumentations
-    ...getWebInstrumentations(),
-
-    new ReactIntegration({
-      // or createReactRouterV4Options
-      router: createReactRouterV5Options({
-        history, // the history object used by react-router
-        Route, // Route component imported from react-router package
-      }),
-    }),
-  ],
-});
-```
-
-To instrument React Router v4, v5 import the `<FaroRoute/>` component and use it instead of the
-React router `<Route />` component, for example:
-
-```tsx
-import { FaroRoute } from '@grafana/faro-react';
-
-// during render
-<Switch>
-  <FaroRoute path="/">
-    <Home />
-  </FaroRoute>
-  {/* ... */}
-</Switch>;
-```
-
-## React ErrorBoundary support
-
-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
-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',
-  },
-
-  instrumentations: [
-    // Load the default Web instrumentations
-    ...getWebInstrumentations(),
-
-    // Must be initialized to get FaroErrorBoundary support
-    new ReactIntegration(),
-  ],
-});
-```
-
-```tsx
-import { FaroErrorBoundary } from '@grafana/faro-react';
-
-// during render
-<FaroErrorBoundary>
-  <App />
-</FaroErrorBoundary>;
-```
-
-or
-
-```tsx
-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
-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>;
-```
-
-## React server side rendering support
-
-Follow this guide to learn how to initialize your Faro instrumentation to support React Server Side
-Rendering (SSR) for:
-
-React Router v6 without a data router:
-
-```tsx
-import { FaroErrorBoundary, setReactRouterV6SSRDependencies } from '@grafana/faro-react';
-setReactRouterV6SSRDependencies({ Routes });
-
-export function renderToString(...) {
-  return reactRenderToString(
-    <FaroErrorBoundary>
-      <StaticRouter location={...}>
-        <App />
-      </StaticRouter>
-    </FaroErrorBoundary>
-  ),
-}
-```
-
-React Router v6 with a data router:
-
-Wrap your data router with `withFaroRouterInstrumentation(dataRouter)` in your routes file.
-
-React Router v5:
-
-```tsx
-import { FaroErrorBoundary, setReactRouterV4V5SSRDependencies } from '@grafana/faro-react';
-setReactRouterV4V5SSRDependencies({ Route, history });
-
-export function renderToString(...) {
-  return reactRenderToString(
-    <FaroErrorBoundary>
-      <StaticRouter location={...}>
-        <App />
-      </StaticRouter>
-    </FaroErrorBoundary>
-  ),
-}
-```
-
-## React component profiling
-
-Follow this guide to setup and use the Faro Profiler to get insights into the render performance of
-a React components.
-
-> WARNING
-> Using the profiler has an impact on performance and should not be used in production.
-
-To use the Faro profiler, import the Faro web-tracing package and initialize Faro-React as follows:
-
-```ts
-import { withFaroProfiler } from '@grafana/faro-react';
-
-export default withFaroProfiler(MyReactComponent);
-```
-
-## Upgrading from a v4, v5, v6 router to data router
-
-This section describes how to upgrade the Faro React router instrumentation if you already have a
-React app instrumented which doesn’t use data routers.
-
-In the `ReactIntegration` call, change the `version` property from `ReactRouterVersion.[V4|V5|V6]` to
-`ReactRouterVersion.V6_data_router`.
-
-If you use React Router v4 or v5 remove the `history` and `Route` dependencies and add the `matchRoutes`
-function exported by `react-router-dom`.
-
-If you use React Router v6 remove the following dependencies from the dependencies object:
-
-- `createRoutesFromChildren`
-- `Routes`
-- `useLocation`
-- `useNavigationType`
-
-The ReactIntegration call should look similar to:
-
-```tsx
-import { matchRoutes } from 'react-router-dom';
-
-import { getWebInstrumentations, initializeFaro, ReactIntegration, ReactRouterVersion } from '@grafana/faro-react';
-
-initializeFaro({
-  // ...
-
-  instrumentations: [
-    // Load the default Web instrumentations
-    ...getWebInstrumentations(),
-
-    new ReactIntegration({
-      router: {
-        version: ReactRouterVersion.V6_data_router,
-        dependencies: {
-          matchRoutes,
-        },
-      },
-    }),
-  ],
-});
-```
+For a complete guide to instrumenting web applications with the Faro-React Web SDK, refer to our
+Grafana Cloud Frontend Observability [documentation](https://grafana.com/docs/grafana-cloud/monitor-applications/frontend-observability/instrument/faro-react/).