Installing AppSignal for Browser

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.

Use this guide to add browser error tracking and web vitals to your application. The Plain JS and React examples also cover distributed tracing, error filtering, masking, and tags. You can generate code for your application in the Browser SDK install flow, or follow the examples below. If you have not added your application to AppSignal yet, follow the new application guide first.

Find your Front-end API key

Find the Front-end API key under Front-end error monitoring on your application’s Push & deploy settings. Use the key for the application and environment you want to monitor. This key is meant to be included in browser code. It is different from the Push API keys used by back-end integrations. The install flow puts your key in the generated code. In the examples below, replace <YOUR_FRONTEND_API_KEY> with your own key.

Generate the snippet in AppSignal

The Browser SDK install flow lets you choose Plain JS or React and select which features to include. It starts with Route template selected. The complete examples below include every option:

Options	What gets included in your snippet
Route template	`setRouteTemplate()` runs when your route changes, so `/users/42` can be reported as `/users/:id`.
Distributed tracing	Adds `tracePropagationTargets` so matching API requests carry a `traceparent` header. Replace the example host with your own. This configures the browser only; the receiving API service also needs tracing instrumentation.
Error filtering	`beforeError` drops errors that match the example browser and extension patterns. Adjust the patterns for your application.
Error tags	`setTags()` adds values such as a plan or tenant to errors after sign-in.
Sensitive data masking	`privacy.dom` masks text or excludes click breadcrumbs from selected elements. Replace the example CSS selectors with your own.

The install flow generates Browser SDK code. Selecting Distributed tracing does not instrument your API service. To see its spans alongside a browser request error, follow the back-end setup as well. Both versions also show how to report an error you catch yourself. The React version includes an error boundary for render errors.

Install the package

Install AppSignal for Browser from the beta tag. Distributed tracing and failed-request reporting require version 1.0.0-beta.7 or later. The install flow currently shows an unversioned command; use one of these commands for the beta release:

npm install @appsignal/browser@beta

yarn add @appsignal/browser@beta

pnpm add @appsignal/browser@beta

Commit your lockfile and review the snippet when you upgrade during the beta.

Initialize the SDK

Import your AppSignal setup before the application code you want to monitor. Replace process.env.NODE_ENV and process.env.APP_REVISION with the equivalent values from your build system. Set appVersion to your release tag or commit SHA so AppSignal can match errors to sourcemaps. These examples include all install flow options. Replace api.example.com/** with your API host and path for distributed tracing. Replace the CSS selectors, tags, and router example with values from your application.

Plain JS
React

1. Initialize AppSignal in appsignal.js.

appsignal.js

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

const IGNORED = [
  /ResizeObserver loop/,
  /^Script error\.?$/,
  /-extension:\/\//,
  /webkit-masked-url/,
];

init({
  key: "<YOUR_FRONTEND_API_KEY>",
  endpoint: "https://appsignal-endpoint.net",
  // Inactive builds send nothing. Replace these with your build values.
  active: process.env.NODE_ENV === "production",
  appVersion: process.env.APP_REVISION,
  // Match your API host and path.
  tracePropagationTargets: ["api.example.com/**"],
  privacy: {
    // Mask text or exclude clicks on these elements.
    dom: { maskText: [".user-email"], blockElement: ["#card-form"] },
  },
  beforeError: (error) => {
    const text = [error.message, error.stack, error.filename].join(" ");
    return IGNORED.some((pattern) => pattern.test(text)) ? null : error;
  },
});

Import it first in your entry point:

main.js

import "./appsignal";

// Start your application after this import.

2. Report route changes from your router. Replace router.on with your router’s navigation hook. Report the initial route too, then report its template on each navigation.

router.js

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

router.on("navigate", (route) => {
  setRouteTemplate(route.pattern); // "/users/:id", not "/users/42"
});

3. Add tags after sign-in. Use values from the signed-in user or account. Call clearTags() on sign-out to clear stored tags.

account.js

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

setTags({ plan: "pro", tenant: "acme" });

4. Report errors you catch yourself. Replace save() with your own operation.

save.js

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

try {
  save();
} catch (error) {
  captureError(error);
}

1. Initialize AppSignal in appsignal.js. Import this file before your React application starts.

appsignal.js

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

const IGNORED = [
  /ResizeObserver loop/,
  /^Script error\.?$/,
  /-extension:\/\//,
  /webkit-masked-url/,
];

init({
  key: "<YOUR_FRONTEND_API_KEY>",
  endpoint: "https://appsignal-endpoint.net",
  // Inactive builds send nothing. Replace these with your build values.
  active: process.env.NODE_ENV === "production",
  appVersion: process.env.APP_REVISION,
  // Match your API host and path.
  tracePropagationTargets: ["api.example.com/**"],
  privacy: {
    // Mask text or exclude clicks on these elements.
    dom: { maskText: [".user-email"], blockElement: ["#card-form"] },
  },
  beforeError: (error) => {
    const text = [error.message, error.stack, error.filename].join(" ");
    return IGNORED.some((pattern) => pattern.test(text)) ? null : error;
  },
});

Import it first in your entry point:

main.jsx

import "./appsignal";

// Start your React application after this import.

2. Report route changes. Render RouteReporter inside your router and pass its current route template as routePattern. React hooks must run inside a component.

RouteReporter.jsx

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

export function RouteReporter({ routePattern }) {
  useEffect(() => {
    setRouteTemplate(routePattern); // "/users/:id", not "/users/42"
  }, [routePattern]);

  return null;
}

See the React route examples for React Router and Next.js.3. Add tags after sign-in. Use values from the signed-in user or account. Call clearTags() on sign-out to clear stored tags.

account.js

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

setTags({ plan: "pro", tenant: "acme" });

4. Catch render errors at your app root. The boundary reports render errors that do not reach the browser’s global error handler.

AppRoot.jsx

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

<ErrorBoundary
  captureError={captureError}
  fallback={<p>This page didn't load. Reload to try again.</p>}
>
  <App />
</ErrorBoundary>

5. Report errors you catch yourself. Replace save() with your own operation.

save.js

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

try {
  save();
} catch (error) {
  captureError(error);
}

If you only need error tracking, breadcrumbs, and web vitals, you can start with a smaller appsignal.js file. Replace <YOUR_APP_REVISION> with your release tag or commit SHA:

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

init({
  key: "<YOUR_FRONTEND_API_KEY>",
  endpoint: "https://appsignal-endpoint.net",
  active: process.env.NODE_ENV === "production",
  appVersion: "<YOUR_APP_REVISION>",
});

Import appsignal.js first in your entry point, as shown above. This smaller setup does not add traceparent headers to your API requests. For every setup, active: false stops the SDK from collecting or sending data. endpoint defaults to the current page’s origin; set it to https://appsignal-endpoint.net unless you proxy AppSignal requests through your own domain. See all configuration options.

Install without a bundler

If your site loads JavaScript with <script> tags and has no bundler, use the UMD build. It exposes the SDK as AppsignalBrowser on window:

<script src="https://cdn.jsdelivr.net/npm/@appsignal/browser@1.0.0-beta.7/dist/browser.umd.js"></script>
<script>
  AppsignalBrowser.init({
    key: "<YOUR_FRONTEND_API_KEY>",
    endpoint: "https://appsignal-endpoint.net",
    appVersion: "<YOUR_APP_REVISION>",
  });
</script>

Replace the version in the URL when you upgrade. A fixed version prevents an unexpected SDK change on your site.

Report the current route

Use this step for a single-page application with routes such as /users/42. Pass the route template, such as /users/:id, when your router navigates. AppSignal uses it to group errors and web vitals by route. The full examples above show where to call setRouteTemplate(). If you do not set a route template, the SDK reports the current page path. That means /users/42 and /users/43 can appear as separate error groups. See React route examples for React Router and Next.js.

Verify the installation

Run a build with active set to true. You can temporarily use active: true in development.
Open the page and run this code in the browser console:
JavaScript
setTimeout(() => { throw new Error("AppSignal test error"); }, 0);
The timer lets the error reach the page’s global error handler. An error thrown directly in the console is usually handled by the console itself.
Open Browser > Errors in AppSignal and find AppSignal test error.

Web vitals appear after the SDK flushes them, such as when the page becomes hidden or the route changes. If no data appears, see Browser troubleshooting.

Content Security Policy

If your site uses a Content Security Policy, allow the configured AppSignal endpoint in its connect-src directive. For example, add the endpoint to your existing allowed sources:

Content-Security-Policy: connect-src 'self' https://appsignal-endpoint.net

Assets hosted on a CDN

Use this step if your site’s JavaScript loads from another origin, such as a CDN. Without cross-origin access, the browser may report only Script error. with no stack or line number. The SDK drops those opaque errors because they cannot be traced back to your code. Serve the script with an Access-Control-Allow-Origin header that permits your page’s origin, and add crossorigin="anonymous" to the script tag:

<script src="https://cdn.example.com/bundle.js" crossorigin="anonymous"></script>

<%= javascript_include_tag "application", :crossorigin => :anonymous %>

Uninstall

Remove the appsignal.js import and other @appsignal/browser calls from your code. Remove any ErrorBoundary imported from @appsignal/browser/react.
Remove the package and update your lockfile with npm uninstall @appsignal/browser, yarn remove @appsignal/browser, or pnpm remove @appsignal/browser. If you installed the UMD build, remove its <script> tag instead.
Deploy the change. The new build stops reporting browser data.
If this AppSignal application was used only for browser monitoring, you can optionally remove the application.

To stop collection without uninstalling, call destroy(). It flushes pending data and stops collection until init() runs again, for example after a page reload.

SDKs & telemetry

Language SDKs

Telemetry tools

Find your Front-end API key

Generate the snippet in AppSignal

Install the package

Initialize the SDK

Install without a bundler

Report the current route

Verify the installation

Content Security Policy

Assets hosted on a CDN

Uninstall

​Find your Front-end API key

​Generate the snippet in AppSignal

​Install the package

​Initialize the SDK

​Install without a bundler

​Report the current route

​Verify the installation

​Content Security Policy

​Assets hosted on a CDN

​Uninstall

Find your Front-end API key

Generate the snippet in AppSignal

Install the package

Initialize the SDK

Install without a bundler

Report the current route

Verify the installation

Content Security Policy

Assets hosted on a CDN

Uninstall