Migrating from AppSignal for JavaScript

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.

@appsignal/browser replaces @appsignal/javascript, its framework integrations, and its plugin packages. This guide maps the old API onto the new one. The new SDK collects breadcrumbs and web vitals after init() and reports errors in the Browser views. Migrate when you are ready to adopt its API and review the changes below.

What changes

One package instead of several. Error tracking, breadcrumbs, and web vitals are all in @appsignal/browser. The new SDK has no matching plugin or framework packages. Some features are built in; others need application code. Functions instead of an instance. There is no client object to create, pass around, or hand to a component. You call init() once and import the functions you need wherever you need them. Uncaught errors are reported without asking. @appsignal/plugin-window-events existed because you had to opt in to them. They are on by default now. The SDK drops opaque cross-origin script errors. Use beforeError to filter other browser or extension noise. Errors report to the browser namespace. @appsignal/javascript reported to frontend, and there is no namespace option any more. New errors appear in the Browser section. Existing frontend errors remain in their current list. Existing incidents in the frontend namespace stay where they are.

Notification settings are configured per namespace, so the ones you set up for frontend do not apply to browser. Set them up again after migrating, or front-end errors will arrive without notifying anyone.

Your existing frontend incidents keep their assignees, states, and severities. The new package reports to the browser namespace. Its new issues start unassigned, as other new issues do. No spans, decorators, or overrides. The new SDK has no equivalent for the old span API. Use setTags() for tags on subsequent errors, and beforeError or beforeBreadcrumb to redact data. The optional context passed to captureError() is not included in ordinary error reports in this beta.

Configuration

`@appsignal/javascript`	`@appsignal/browser`
`new Appsignal({ ... })`	`init({ ... })`
`key`	`key`, unchanged. The same Front-end API key.
`revision`	`appVersion`
`namespace`	No equivalent. Errors always report to `browser`.
`ignoreErrors: [/pattern/]`	`beforeError`, returning `null` for a match.
`matchBacktracePaths`	No equivalent. Contact us if you rely on it.
No equivalent	`active`, to switch the SDK off completely outside production.
No equivalent	`endpoint`, `errors.sampleRate`, `breadcrumbs.`, `privacy.`.

Before:

import Appsignal from "@appsignal/javascript";
import { plugin as windowEvents } from "@appsignal/plugin-window-events";
import { plugin as consoleBreadcrumbs } from "@appsignal/plugin-breadcrumbs-console";
import { plugin as networkBreadcrumbs } from "@appsignal/plugin-breadcrumbs-network";

export const appsignal = new Appsignal({
  key: "<YOUR_FRONTEND_API_KEY>",
  revision: "<YOUR_APP_REVISION>",
  ignoreErrors: [/ResizeObserver/],
});

appsignal.use(windowEvents());
appsignal.use(consoleBreadcrumbs());
appsignal.use(networkBreadcrumbs());

After:

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>",
  beforeError: (event) => (/ResizeObserver/.test(event.message) ? null : event),
});

Uncaught exceptions, console breadcrumbs, and network breadcrumbs are all covered by that single call.

Methods

`@appsignal/javascript`	`@appsignal/browser`
`appsignal.sendError(error)`	`captureError(error)`
`appsignal.sendError(error, (span) => span.setTags({ ... }))`	No direct per-error tag equivalent. `setTags({ ... })` applies to subsequent errors until those tags are cleared.
`appsignal.wrap(fn)`	No equivalent. Use `try`/`catch` with `captureError`.
`appsignal.addBreadcrumb({ category, action, message, metadata })`	`addBreadcrumb({ category, message, data })`. There is no `action` field, and `metadata` is now `data`.
`appsignal.createSpan()`, `appsignal.send(span)`	No equivalent.
`appsignal.addDecorator(fn)`	`setTags()` for tags, `beforeError` for everything else.
`appsignal.addOverride(fn)`	`beforeError` and `beforeBreadcrumb`.
`appsignal.use(plugin())`	No equivalent. Built in.
No equivalent	`setRouteTemplate()`, which groups errors and web vitals by route.
No equivalent	`setTags()`, `clearTags()`, `destroy()`.

appsignal.wrap() ran your code and reported thrown errors. Its returned promise rejected with the same error, so your code could catch it. The direct replacement makes both halves explicit:

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

try {
  await riskyOperation();
} catch (error) {
  captureError(error);
  throw error;
}

Framework integrations

Package	Replacement
`@appsignal/react`	`@appsignal/browser/react`. Pass `captureError` instead of an `instance` prop. There is no `override` prop, and no separate `LegacyBoundary` component.
`@appsignal/vue`, `@appsignal/angular`, `@appsignal/preact`, `@appsignal/ember`, `@appsignal/stimulus`	No equivalent. Errors these frameworks let through are reported automatically. Report the ones the framework catches itself with `captureError()` from its error handler.
`@appsignal/urql`	No equivalent. Report GraphQL errors with `captureError()` from your client’s error exchange.
`@appsignal/plugin-path-decorator`	`setRouteTemplate()`, which is the built-in equivalent.

The React error boundary changes shape:

import { ErrorBoundary } from "@appsignal/react";
import { appsignal } from "./appsignal";

<ErrorBoundary instance={appsignal} action="Dashboard" tags={{ plan: "pro" }}>
  <Dashboard />
</ErrorBoundary>

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

<ErrorBoundary captureError={captureError}>
  <Dashboard />
</ErrorBoundary>

The new boundary has no action prop. Call setRouteTemplate() for the route used to group errors. If you use setTags(), call it after init() and clear it when those tags should stop applying.

Steps to migrate

Install @appsignal/browser@beta and remove @appsignal/javascript along with every @appsignal/plugin-* and framework integration package.
Replace your new Appsignal({ ... }) call with init({ ... }), using the configuration table in this guide. Add endpoint and active.
Replace sendError with captureError, and wrap with try/catch.
Move ignoreErrors patterns, decorators, and overrides into beforeError and beforeBreadcrumb.
Call setRouteTemplate() on each router navigation.
Swap the React error boundary import, if you use one.
Set up notification settings for the browser namespace.
Deploy, then confirm errors and web vitals arrive in the Browser section of your application.

Sourcemaps need no change. They are still matched on the revision string, which appVersion now supplies.

SDKs & telemetry

Language SDKs

Telemetry tools

Migrating from AppSignal for JavaScript

What changes

Configuration

Methods

Framework integrations

Steps to migrate

​What changes

​Configuration

​Methods

​Framework integrations

​Steps to migrate

What changes

Configuration

Methods

Framework integrations

Steps to migrate