JavaScript

Browser JavaScript

Install the SnagSpy browser SDK, capture your first error, and make the stack trace readable. About fifteen minutes.

Prerequisites

Using a framework? This guide covers plain JavaScript. Guides for React, Vue, Next.js and the rest do not exist yet — the SDK works inside those applications, but nothing here is specific to their lifecycle.

You need:

A SnagSpy account and a project
That project’s DSN
An application running in a browser

1Install

The browser SDK is a separate npm package from the CLI, because it ships inside your application and becomes a dependency of yours.

Not published yet The @snagspy/replay package is not on the public npm registry yet, so the command below will fail today. Contact us for a tarball in the meantime. The CLI is published and installs normally.

npm

npm install @snagspy/replay

2Configure

Initialise error monitoring

Call init as early as you can — an error thrown before it is not captured, because the global handlers are not installed yet. init never throws: an invalid DSN produces a warning and an inert client, never a broken page.

JavaScript

import { init } from '@snagspy/replay/errors'

const snagspy = init({
  dsn: globalThis._importMeta_.env.VITE_SNAGSPY_DSN,
  release: globalThis._importMeta_.env.VITE_COMMIT_SHA,
  environment: 'production',
})

The options that matter

dsn is the only required field. The next three change what you see in the dashboard:

release: The version this build belongs to, a git sha for example. It is what deployment correlation keys on, and the fallback the resolver uses when a frame carries no debug id.
serviceName: The name this page reports as. Defaults to the hostname. A single-page app and its API reporting the same name would merge two services’ issues into one list.
environment: production, staging, and so on.
beforeSend: Last chance to inspect or drop an event. It runs after redaction, so you see what would actually be sent.

Make the stack trace readable

A minified stack names t.js:1:4821. Upload the build’s source maps with the CLI, passing the same release you gave init — that is what ties the two together.

Shell

npx snagspy upload --project <project-id> --release "$COMMIT_SHA" ./dist

Join session replay

The root entry is the recorder, not error monitoring: its init returns a Session. Pass its sessionID to error monitoring to join the two.

JavaScript

import { init as record } from '@snagspy/replay'
import { init } from '@snagspy/replay/errors'

const session = record({ dsn: DSN })
const snagspy = init({ dsn: DSN, sessionID: session.sessionID ?? undefined })

3Verify your setup

Throw an error from the page itself and watch it arrive.

HTML

<button onclick="throw new Error('SnagSpy test error')">
  Break the world
</button>

captureException

captureException is for errors your code caught: their default level is warning, because the application carried on. An unhandled error is always error.

JavaScript

try {
  risky()
} catch (error) {
  snagspy.captureException(error, { level: 'error' })
}

4Next steps

At this point your application’s errors reach SnagSpy. From here:

Upload source maps from CI →Connect a backend with OpenTelemetry →Read the full reference →