Browser integration guide

Typical installation time: 3 minutes

Hi there! You’ve found Honeybadger’s guide to JavaScript error and exception tracking in browsers. Once installed, Honeybadger will automatically report errors from your client-side JavaScript application.

Installation

To use our hosted CDN, place the following code between the <head></head> tags of your page:

<script
  src="//js.honeybadger.io/v6.12/honeybadger.min.js"
  type="text/javascript"
></script>

<script type="text/javascript">
  Honeybadger.configure({
    apiKey: "PROJECT_API_KEY",
    environment: "production",
    revision: "git SHA/project version",
  });
</script>

Here’s a video walkthrough of a basic, global installation:

Non-blocking loading

The default CDN installation above loads honeybadger.min.js synchronously so that Honeybadger’s window.onerror handler is in place before any other scripts run. This ensures automatic error catching works for all errors, but it means the script is render-blocking.

If page load performance is a concern, you can load the script with the defer attribute:

<script
  src="//js.honeybadger.io/v6.12/honeybadger.min.js"
  type="text/javascript"
  defer
></script>

<script type="text/javascript">
  document.addEventListener("DOMContentLoaded", function () {
    Honeybadger.configure({
      apiKey: "PROJECT_API_KEY",
      environment: "production",
      revision: "git SHA/project version",
    });
  });
</script>

The defer attribute makes the CDN script download without blocking render and execute after the HTML is parsed. Since defer only applies to external scripts, the inline configure call uses a DOMContentLoaded listener to ensure it runs after the deferred script has executed.

Trade-offs to be aware of:

If you only use manual Honeybadger.notify() calls (i.e., enableUncaught and enableUnhandledRejection are both false), then defer can be used safely as long as your notify() calls also run after the notifier has loaded — for example, in deferred or bundled application scripts.
If you rely on automatic error catching (the default), any uncaught errors or unhandled promise rejections that occur before the deferred script executes will not be captured. In practice, this is a small window — deferred scripts run after the DOM is parsed but before the DOMContentLoaded event.

As an alternative, bundling Honeybadger with npm eliminates the extra network request entirely and gives you full control over load timing.

Installing via NPM/YARN

# npm
npm install @honeybadger-io/js --save

# yarn
yarn add @honeybadger-io/js

You can include honeybadger.js from the node_modules directory.

Bundling with ESM (esbuild), CommonJS (Browserify/Webpack), etc.

// ES module
import Honeybadger from '@honeybadger-io/js';
// CommonJS
var Honeybadger = require("path/to/honeybadger");

Honeybadger.configure({
  apiKey: 'PROJECT_API_KEY',
  environment: 'production',
  revision: 'git SHA/project version'
});

See an example browserify + honeybadger.js project.
See an example webpack + honeybadger.js project.

RequireJS (AMD)

requirejs(["path/to/honeybadger"], function(Honeybadger) {
  Honeybadger.configure({
    apiKey: 'PROJECT_API_KEY',
    environment: 'production',
    revision: 'git SHA/project version'
  });
});

See an example requirejs + honeybadger.js project.

Reporting errors

By default Honeybadger will report all uncaught exceptions automatically using our window.onerror handler.

You can also manually notify Honeybadger of errors and other events in your application code:

try {
  // ...error producing code...
} catch (error) {
  Honeybadger.notify(error);
}

Identifying users

Honeybadger can track what users have encountered each error. To identify the current user in error reports, add a user identifier and/or email address with Honeybadger.context:

Honeybadger.setContext({
  user_id: 123,
  user_email: "user@example.com",
});

Tracking deploys

Honeybadger can also keep track of application deployments, and link errors to the version which the error occurred in. Here’s a simple curl script to record a deployment:

HONEYBADGER_ENV="production" \
HONEYBADGER_REVISION="$(git rev-parse HEAD)" \
HONEYBADGER_REPOSITORY="$(git config --get remote.origin.url)" \
HONEYBADGER_API_KEY="Your project API key" \
  && curl -g "https://api.honeybadger.io/v1/deploys?deploy[environment]=$HONEYBADGER_ENV&deploy[local_username]=$USER&deploy[revision]=$HONEYBADGER_REVISION&deploy[repository]=$HONEYBADGER_REPOSITORY&api_key=$HONEYBADGER_API_KEY"

Be sure that the same revision is also configured in the honeybadger.js library. Read more about deploy tracking in the API docs.

Tracking deploys from Netlify

If you are deploying your site to Netlify, you can notify Honeybadger of deployments via Netlify’s webhooks. Go to the Deploy notifications section of the Build & deploy tab for your site settings, and choose to add an Outgoing webhook notification. Choose Deploy succeeded as the event to listen for, and use this format for your URL:

https://api.honeybadger.io/v1/deploys/netlify?api_key=YOUR_HONEYBADGER_API_KEY_HERE

The environment that will be reported to Honeybadger defaults to the Netlify environment that was deployed, but you can override that with &environment=CUSTOM_ENV in the webhook URL, if you like.

Source map support

Honeybadger can automatically un-minify your code if you provide a source map along with your minified JavaScript files. See our Source Map Guide for details.

Collect user feedback

When an error occurs, a form can be shown to gather feedback from your users. Read more about this feature here.