@grafana/faro-react 1.6.0 → 1.7.0

package/README.md

@@ -4,36 +4,108 @@ 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
+- 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
 
-## Installation
+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.
 
-### React Router without Data Routers
+Faro-React is a distribution of the Faro Web SDK for project using React, which offers easier
+integrations and the following features:
 
-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.
+- **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
+- **Server side rendering (SSR) support**
+
+## 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:
+
+```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
+
+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
+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 { getWebInstrumentations, initializeFaro, ReactIntegration, ReactRouterVersion } from '@grafana/faro-react';
-import { TracingInstrumentation } from '@grafana/faro-web-tracing';
 
 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(),
 
-    // 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: {
@@ -44,60 +116,93 @@ initializeFaro({
           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
-        },
-      },
     }),
   ],
 });
 ```
 
-### Use with React Router with Data Routers
+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 { matchRoutes } from 'react-router-dom';
+import { createBrowserHistory } from 'history';
+import { Route } from 'react-router-dom';
 
 import { getWebInstrumentations, initializeFaro, ReactIntegration, ReactRouterVersion } from '@grafana/faro-react';
-import { TracingInstrumentation } from '@grafana/faro-web-tracing';
+
+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(),
 
-    // 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,
+        version: ReactRouterVersion.V5, // or ReactRouterVersion.V4,
         dependencies: {
-          matchRoutes,
+          history, // the history object used by react-router
+          Route, // Route component imported from react-router package
         },
       },
     }),
   ],
 });
+```
 
-// 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.
+To instrument React Router v4, v5 import the `<FaroRoute/>` component and use it instead of the
+React router `<Route />` component, for example:
 
-const reactBrowserRouter = createBrowserRouter([
-  //...
-]);
+```tsx
+import { FaroRoute } from '@grafana/faro-react';
 
-const browserRouter = withFaroRouterInstrumentation(reactBrowserRouter);
+// during render
+<Switch>
+  <FaroRoute path="/">
+    <Home />
+  </FaroRoute>
+  {/* ... */}
+</Switch>;
 ```
 
-### Error Boundary
+## 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.
 
 ```tsx
 import { FaroErrorBoundary } from '@grafana/faro-react';
@@ -116,130 +221,158 @@ import { withErrorBoundary } from '@grafana/faro-react';
 export default withErrorBoundary(App);
 ```
 
-#### pushErrorOptions prop
+### 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
+// ...
 
+<FaroErrorBoundary>
+  <MyComponent />
+</FaroErrorBoundary>
+```
+
+```tsx
 import { FaroErrorBoundary, PushErrorOptions } from '@grafana/faro-react';
 
 const pushErrorOptions: PushErrorOptions = {
   type: "Custom Error Type"
   context: {
     foo: "bar",
-    baz: "qux"
+    baz: "abc"
   },
-  // ...
-}
+};
 
 // during render
-<FaroErrorBoundary pushErrorOptions={pushErrorOptions}>
+<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>;
 ```
 
-### Router
+## React erver side rendering support
 
-#### V6
+Follow this guide to learn how to initialize your Faro instrumentation to support React Server Side
+Rendering (SSR) for:
 
-```tsx
-import { FaroRoutes } from '@grafana/faro-react';
+React Router v6 without a data router:
 
-// during render
-<FaroRoutes>
-  <Route path="/" element={<Home />} />
-  {/* ... */}
-</FaroRoutes>;
+```tsx
+import { FaroErrorBoundary, setReactRouterV6SSRDependencies } from '@grafana/faro-react';
+setReactRouterV6SSRDependencies({ Routes });
+
+export function renderToString(...) {
+  return reactRenderToString(
+    <FaroErrorBoundary>
+      <StaticRouter location={...}>
+        <App />
+      </StaticRouter>
+    </FaroErrorBoundary>
+  ),
+}
 ```
 
-#### V6 Data Router
+React Router v6 with a data router:
 
-1. Create a data router (createBrowserRouter, createHashRouter, createMemoryRouter)
-2. Instrument the data router to receive route changes by wrapping it with `withFaroRouterInstrumentation()`
+Wrap your data router with `withFaroRouterInstrumentation(dataRouter)` in your routes file.
 
-```ts
-const reactBrowserRouter = createBrowserRouter([
-  //...
-]);
+React Router v5:
 
-const browserRouter = withFaroRouterInstrumentation(reactBrowserRouter);
+```tsx
+import { FaroErrorBoundary, setReactRouterV4V5SSRDependencies } from '@grafana/faro-react';
+setReactRouterV4V5SSRDependencies({ Route, history });
+
+export function renderToString(...) {
+  return reactRenderToString(
+    <FaroErrorBoundary>
+      <StaticRouter location={...}>
+        <App />
+      </StaticRouter>
+    </FaroErrorBoundary>
+  ),
+}
 ```
 
-#### V4/v5
+## React component profiling
 
-```tsx
-import { FaroRoute } from '@grafana/faro-react';
+Follow this guide to setup and use the Faro Profiler to get insights into the render performance of
+a React components.
 
-// during render
-<Switch>
-  <FaroRoute path="/">
-    <Home />
-  </FaroRoute>
-  {/* ... */}
-</Switch>;
+> 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 instrumented V6 router to V6 data router
+## 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`.
 
-##### Change router config
+If you use React Router v4 or v5 remove the `history` and `Route` dependencies and add the `matchRoutes`
+function exported by `react-router-dom`.
 
-1. Change `version` property from `ReactRouterVersion.V6` to `ReactRouterVersion.V6_data_router`.
-2. Remove the following dependencies from the dependencies object
+If you use React Router v6 remove the following dependencies from the dependencies object:
 
 - `createRoutesFromChildren`
 - `Routes`
 - `useLocation`
 - `useNavigationType`
 
-Example: updating dependencies
+The ReactIntegration call should look similar to:
+
+```tsx
+import { matchRoutes } from 'react-router-dom';
+
+import { getWebInstrumentations, initializeFaro, ReactIntegration, ReactRouterVersion } from '@grafana/faro-react';
 
-```ts
 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,
         },
       },
     }),
   ],
 });
 ```
-
-##### Change Router instrumentation
-
-1. Remove `<FaroRoutes>` component. This will not work anymore with V6 data routers.
-2. Create a data router and wrap it with `withFaroRouterInstrumentation(dataRouter)`
-
-Example: Instrument Router
-
-```ts
-const reactBrowserRouter = createBrowserRouter([
-  // your routes
-]);
-
-const browserRouter = withFaroRouterInstrumentation(reactBrowserRouter);
-```
-
-### Profiler
-
-```tsx
-import { withFaroProfiler } from '@grafana/faro-react';
-
-export default withFaroProfiler(App);
-```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grafana/faro-react",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Faro package that enables easier integration in projects built with React.",
   "keywords": [
     "observability",
@@ -52,8 +52,8 @@
     "quality:circular-deps": "madge --circular ."
   },
   "dependencies": {
-    "@grafana/faro-web-sdk": "^1.6.0",
-    "@grafana/faro-web-tracing": "^1.6.0",
+    "@grafana/faro-web-sdk": "^1.7.0",
+    "@grafana/faro-web-tracing": "^1.7.0",
     "hoist-non-react-statics": "^3.3.2"
   },
   "devDependencies": {
@@ -71,5 +71,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "108fd2cbd0ff73398599bb87a020215c170e07b9"
+  "gitHead": "b06dd9c3b974d3d9103f7a045d1e86207ba007d0"
 }