JavaScript

On this page, we get you up and running with Sentry's JavaScript SDK, so that it will automatically report errors and exceptions in your application.

Using a framework? Take a look at our specific guides to get started.

Install the Package

Sentry captures data by using an SDK within your application’s runtime. Add the Sentry SDK to your application:

Copied
# Using yarn
$ yarn add @sentry/browser

# Using npm
$ npm install --save @sentry/browser

Configure and Verify

init Sentry as soon as possible in your app, to make sure it can monitor everything that follows it. Once this is done, all unhandled exceptions are automatically captured by Sentry.

The snippet below includes an intentional error, so you can test that everything is working as soon as you set it up. To view and resolve the recorded error, log into sentry.io and open your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved.

Copied
import * as Sentry from "@sentry/browser";

Sentry.init({ dsn: "https://examplePublicKey@o0.ingest.sentry.io/0" });

myUndefinedFunction(); // To test your setup

Capture Errors

By including and configuring Sentry, our JavaScript SDK automatically attaches global handlers to capture uncaught exceptions and unhandled promise rejections, as described in the official ECMAScript 6 standard. You can disable this default behavior by changing the onunhandledrejection option to false in your GlobalHandlers integration and manually hook into each event handler, then call Sentry.captureException or Sentry.captureMessage directly.

You may also need to manage your configuration if you are using a third-party library to implement promises. Also, remember that browsers often implement security measures that can block error reporting when serving script files from different origins.

Learn more about how to manually capture errors or enable message capture with Sentry's JavaScript SDK in Advanced Usage.

Automatically Enrich Error Data

Events sent by the JavaScript SDK to Sentry are enriched with data that helps identify the source of the event. Much of this data is sent automatically - including the error context and environment - as well as the trail of events that led up to the event, which we call breadcrumbs. You don't need to configure these, though you may modify them.

Learn more about the data sent to with events in Event Context.

Set the Release Version

When you configure Sentry to include the version of your application, Sentry can tell you about regressions as well as detailed information about the suspect commit. You will also need releases for source maps.

Use the process.env.npm_package_version:

Copied
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  release: "my-project-name@" + process.env.npm_package_version,
});

Learn more about what releases can do in our documentation for releases.

Upload Source Maps

We highly recommend you incorporate source maps to receive the full benefit of error tracking and monitoring. See our source maps documentation to learn more.

Monitor Performance

Install performance monitoring using Sentry’s JavaScript SDK using both the @sentry/browser and @sentry/tracing packages:

Copied
# Using yarn
$ yarn add @sentry/browser @sentry/tracing

# Using npm
$ npm install --save @sentry/browser @sentry/tracing

Initialize the integration in your call to Sentry.init:

Copied
import * as Sentry from "@sentry/browser";
import { Integrations } from "@sentry/tracing";
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  release: "my-project-name@" + process.env.npm_package_version,
  integrations: [new Integrations.BrowserTracing()],
  tracesSampleRate: 1.0, // Be sure to lower this in production
});

Performance data is transmitted using a new event type called “transactions”, which you can learn about in Distributed Tracing. To capture transactions, install the performance package and configure your SDK to set the tracesSampleRate configuration to a nonzero value. The example configuration above will transmit 100% of captured transactions; lower this value in production to avoid consuming your quota too quickly.

Learn more about sampling in Filtering Events Reported to Sentry.

Next Steps

  • Manage Configuration Options

    Sentry's JavaScript SDK includes many configuration options that are automatically set. You can configure your SDK using the options outlined in these pages.

  • Enrich Event Data

    When your SDK sends an event to Sentry, the event is enriched with data. Learn more about the data that helps identify the source of the event and includes information both pertinent to the event as well as a full picture of what led up to it.

  • Review and Manage Integrations

    Integrations extend the functionality of our JavaScript SDK to cover common libraries and environments automatically. Learn more about our default and pluggable integrations.

  • Troubleshooting

    If you need help solving issues with Sentry's JavaScript SDK, you can read the edge cases documented here.

For a deep dive into our JavaScript SDK, check out our GitHub repo.

You can edit this page on GitHub.