Get started with JavaScript

Getting Opbeat set up to log exceptions in frontend JavaScript is easy, and there are various ways you can tweak it to fit to your needs.

Installation

To start logging frontend JavaScript exceptions, create a new app in your Opbeat organization and select “JavaScript” (or one of the supported front-end frameworks) as the language.

Load from CDN

The module can be loaded from our fast and reliable CDN server.

Include the following snippet before your main application. Typically in the <head> section.

<script src="https://d3tvtfb6518e3e.cloudfront.net/3/opbeat.min.js"
        data-org-id="<ORGANIZATION-ID>"
        data-app-id="<APP-ID>">
</script>

Install from npm

The module can also be installed using npm. The package is called opbeat-js.

Run the following command in your project directory:

$ npm install opbeat-js --save

And include it in your application:

<script src="node_modules/opbeat-js/opbeat.min.js"
        data-org-id="<ORGANIZATION-ID>"
        data-app-id="<APP-ID>">
</script>

Install from bower

The module can also be installed using bower.

Run the following command in your project directory:

$ bower install opbeat-js --save

And include it in your application:

<script src="bower_components/opbeat-js/opbeat.min.js"></script>

Configuration

Any configuration option can be set either in the options object or by using hyphen-separated attributes on the opbeat.js script tag. All the available configuration options are listed in the API documentation.

<script type="text/javascript">
_opbeat('config', {
   orgId: '<ORGANIZATION-ID>',
   appId: '<APP-ID>'
});
</script>

Asynchronous loading

If you want to ensure that downloading the Opbeat module does not block loading the page, you can load it asynchronously:

<script src="https://d3tvtfb6518e3e.cloudfront.net/3/opbeat.min.js"
        data-org-id="<ORGANIZATION-ID>"
        data-app-id="<APP-ID>"
        async
></script>

Important: When loading Opbeat asynchronously, errors that occur while Opbeat is not loaded completely yet might not be caught.

If the Opbeat module is loaded asynchronously you should use the following method to initialize and configure it.

<script type="text/javascript">
_opbeat = window._opbeat || function() {
  (window._opbeat.q = window._opbeat.q || []).push(arguments)
};

_opbeat('config', {
   // Configuration options
});
</script>

Setting up CORS

On browsers that support Cross-Origin Resource Sharing (CORS), Opbeat is able to collect much more detailed information about exceptions.

To enable CORS, first set up your server to return the right Access-Control-Allow-Origin headers. enable-cors.org has a comprehensive guide for different server software.

Then, add the crossorigin attribute to <script> tags (only do this to JavaScript you host yourself or have verified that the respective server returns the correct Access-Control-Allow-Origin headers). Here’s an example:

<script src="/static/js/scripts.js" crossorigin></script>

Note: make sure to force browser caches to invalidate.

Because browsers cache resources including the Access-Control-Allow-Origin header, you need to force these caches to invalidate. The right way to invalidate depends a bit on your setup, but the easiest one is to change the URLs of your scripts by appending a query string parameter, e.g.:

<script src="/static/js/scripts.js?v1" crossorigin></script>

Source Maps

We support source maps to reverse JavaScript minification. If your build script generates source maps, and includes the sourceMappingURL in the generated JavaScript, we will try to detect and download the source map.

Read more in the Source Maps for frontend JavaScript article.

Capturing exceptions manually

You can capture errors and exceptions manually by using the captureException() method.

Example:

<script type="text/javascript">
    try {
        return multiply(add(a, b), a, b) / c
    } catch (e) {
        _opbeat('captureException', e)
    }
</script>

Adding user context

You can add information about the logged-in user to errors by using the setUserContext() method.

Example:

<script type="text/javascript">
    _opbeat('setUserContext', {
        username: "{{ user_name }}",
        email: "{{ user_email }}",
        id: "{{ user_id }}"
    });
</script>

Adding extra data

You can add any extra information to errors by using the setExtraContext() method.

Example:

<script type="text/javascript">
    _opbeat('setExtraContext', {
        user_type: "{{ user.type }}",
        org_name: "{{ organization.name }}",
        org_plan: "{{ organization.billing.plan }}"
    });
</script>