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 swallows errors thrown during rendering: instead of reaching window, they unmount the tree. An error boundary is the only way to see them. AppSignal for Browser ships one as a subpath export of the package, so there is nothing extra 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>

captureError is passed as a prop rather than imported by the boundary itself, so the same component works for both the ES module and the UMD build. Errors caught this way arrive with the name of the component that threw, and the full list of components it was nested inside at the time. That is usually enough to find the problem without reproducing it.

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 where a failure has a sensible fallback: around each route, and around individual widgets that can be missing without breaking the page. One boundary at the root catches everything, but replaces your whole application with the fallback.

Reporting the current route

Report the current route on every navigation, using the template such as /orders/:id rather than the resolved path.

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

function RouteReporter() {
  const matches = useMatches();

  useEffect(() => {
    const route = matches.at(-1);
    if (route) setRouteTemplate(route.id);
  }, [matches]);

  return null;
}

"use client";

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

export function RouteReporter() {
  const pathname = usePathname();

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

  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;
}

Import your AppSignal setup before your router. The SDK and most 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, { orderId: order.id });
    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