> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating from AppSignal for JavaScript

<Note>
  Browser monitoring is a beta [AppSignal Labs](/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](https://discord.gg/EjF6ykYx63).
</Note>

`@appsignal/browser` replaces [`@appsignal/javascript`](/front-end), 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.

<h2 id="what-changes">
  What changes
</h2>

**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.

<Warning>
  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.
</Warning>

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.

<h2 id="configuration">
  Configuration
</h2>

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

Before:

<CodeGroup>
  ```js @appsignal/javascript theme={null}
  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());
  ```
</CodeGroup>

After:

<CodeGroup>
  ```js @appsignal/browser theme={null}
  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),
  });
  ```
</CodeGroup>

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

<h2 id="methods">
  Methods
</h2>

| `@appsignal/javascript` | `@appsignal/browser` |
| - | - |
| `appsignal.sendError(error)` | [`captureError(error)`](/browser/error-tracking#reporting-errors-manually) |
| `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 })`](/browser/breadcrumbs#adding-your-own-breadcrumbs). 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:

<CodeGroup>
  ```js JavaScript theme={null}
  import { captureError } from "@appsignal/browser";

  try {
    await riskyOperation();
  } catch (error) {
    captureError(error);
    throw error;
  }
  ```
</CodeGroup>

<h2 id="framework-integrations">
  Framework integrations
</h2>

| Package | Replacement |
| - | - |
| `@appsignal/react` | [`@appsignal/browser/react`](/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:

<CodeGroup>
  ```jsx @appsignal/react theme={null}
  import { ErrorBoundary } from "@appsignal/react";
  import { appsignal } from "./appsignal";

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

  ```jsx @appsignal/browser/react theme={null}
  import { captureError } from "@appsignal/browser";
  import { ErrorBoundary } from "@appsignal/browser/react";

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

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.

<h2 id="steps-to-migrate">
  Steps to migrate
</h2>

1. Install `@appsignal/browser@beta` and remove `@appsignal/javascript` along with every `@appsignal/plugin-*` and framework integration package.
2. Replace your `new Appsignal({ ... })` call with `init({ ... })`, using the configuration table in this guide. Add `endpoint` and `active`.
3. Replace `sendError` with `captureError`, and `wrap` with `try`/`catch`.
4. Move `ignoreErrors` patterns, decorators, and overrides into `beforeError` and `beforeBreadcrumb`.
5. Call `setRouteTemplate()` on each router navigation.
6. Swap the React error boundary import, if you use one.
7. Set up notification settings for the `browser` namespace.
8. 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.