AppSignal for Browser with React

Browser monitoring is a beta AppSignal Labs feature. The @appsignal/browser package is published under the beta tag on npm, and its configuration and API may still change between beta releases. Share feedback in our Discord community.

React render errors do not reliably reach the browser’s global error handler. Wrap the affected part of your app in an error boundary to report them. AppSignal for Browser includes one at @appsignal/browser/react; there is no extra package to install. Optional: React 16.8 or later, if you want to use the error boundary shipped with the package.

Catching render errors

import { captureError } from "@appsignal/browser";
import { ErrorBoundary } from "@appsignal/browser/react";

<ErrorBoundary
  captureError={captureError}
  fallback={<p>Something went wrong.</p>}
>
  <App />
</ErrorBoundary>

Pass captureError as a prop so the boundary can report errors it catches. The boundary reports the caught error. Its onError callback also receives React’s component stack for your own handling. In this beta, that component stack is not included in ordinary error reports.

Recovering from an error

Pass a function as fallback to give the user a way to try again. It receives the error and a reset function, which clears the error and renders the children again:

<ErrorBoundary
  captureError={captureError}
  fallback={(error, reset) => (
    <div>
      <p>{error.message}</p>
      <button onClick={reset}>Try again</button>
    </div>
  )}
>
  <Dashboard />
</ErrorBoundary>

Wrapping a single component

withErrorBoundary wraps one component, which is convenient for widgets that should fail without taking the page down:

import { captureError } from "@appsignal/browser";
import { withErrorBoundary } from "@appsignal/browser/react";

const SafeRevenueWidget = withErrorBoundary(RevenueWidget, {
  captureError,
  fallback: <p>This widget is unavailable.</p>,
});

Props

Prop	Type	Description
`captureError`	`function`	Required. The `captureError` function from `@appsignal/browser`.
`fallback`	node or `(error, reset) => node`	What to render after an error. Renders nothing when omitted.
`onError`	`(error, componentStack) => void`	Called before the error is sent to AppSignal.

Place boundaries around routes or widgets with a useful fallback. A failed widget can then leave the rest of the page working. One boundary at the root catches everything, but replaces your whole application with the fallback.

Reporting the current route

Report the current route on initial load and after each navigation. Pass a pattern such as /orders/:id, not the resolved URL /orders/42. React Router route IDs and Next.js App Router’s usePathname() do not supply that pattern automatically. The React Router example uses a data router such as createBrowserRouter; render RouteReporter inside it.

import { useEffect } from "react";
import { useMatches } from "react-router";
import { setRouteTemplate } from "@appsignal/browser";

// In your route configuration, add a template to each route's handle:
// { path: "/orders/:id", element: <OrderPage />,
//   handle: { routeTemplate: "/orders/:id" } }

function RouteReporter() {
  const matches = useMatches();
  const template = [...matches].reverse()
    .find((match) => typeof match.handle?.routeTemplate === "string")
    ?.handle.routeTemplate;

  useEffect(() => {
    setRouteTemplate(template ?? null);
  }, [template]);

  return null;
}

"use client";

import { useEffect } from "react";
import { usePathname } from "next/navigation";
import { setRouteTemplate } from "@appsignal/browser";

export function RouteReporter({ routeTemplate }) {
  const pathname = usePathname(); // Triggers an update on navigation

  useEffect(() => {
    setRouteTemplate(routeTemplate);
  }, [pathname, routeTemplate]);

  return null;
}

import { useEffect } from "react";
import { useRouter } from "next/router";
import { setRouteTemplate } from "@appsignal/browser";

export function RouteReporter() {
  const { pathname } = useRouter();

  useEffect(() => {
    setRouteTemplate(pathname); // e.g. "/orders/[id]"
  }, [pathname]);

  return null;
}

With Next.js App Router, render RouteReporter from the matching route. For example, pass routeTemplate="/orders/[id]" from app/orders/[id]/page.jsx. usePathname() returns the resolved URL, such as /orders/42, so do not use it as the template.

Import your AppSignal setup before your router. The SDK and some routers both patch history.pushState, and the SDK composes with an existing patch rather than replacing it. Loading the router first can leave client-side navigation unreported.

Reporting errors from event handlers and effects

An error boundary catches errors thrown during rendering. It does not catch errors thrown in an event handler, a setTimeout, or a rejected promise inside an effect. Uncaught ones reach window and are reported automatically. For the rest, report them yourself:

import { captureError } from "@appsignal/browser";

async function onSubmit(order) {
  try {
    await submitOrder(order);
  } catch (error) {
    captureError(error);
    setStatus("failed");
  }
}

SDKs & telemetry

Language SDKs

Telemetry tools

Catching render errors

Recovering from an error

Wrapping a single component

Props

Reporting the current route

Reporting errors from event handlers and effects

​Catching render errors

​Recovering from an error

​Wrapping a single component

​Props

​Reporting the current route

​Reporting errors from event handlers and effects

Catching render errors

Recovering from an error

Wrapping a single component

Props

Reporting the current route

Reporting errors from event handlers and effects