Lazy-Loading Sentry

If you're concerned about the performance impact of loading the full SDK before any of the rest of your JavaScript, you have the option of lazy-loading it - either immediately after your other JavaScript or not until it's needed - by using our SDK Loader.

The loader is a small wrapper around the SDK, which allows you to:

• Postpone full SDK loading - either until immediately after the rest of your JavaScript or until the SDK is needed - without losing the ability to begin catching unhandled errors and promise rejections early in your pageload.
• Automatically use the latest stable version of the SDK.

The loader is about ~1 KB gzipped and includes the Sentry.init call with your DSN.

Using the Loader

To use the loader, go in the Sentry UI to Settings -> Projects -> Client Keys (DSN), and then press the Configure button. Copy the script tag from the JavaScript Loader section, and include it as the first script on your page. (By including it first, you allow it to catch and buffer events from any subsequent scripts, while still ensuring the full SDK doesn't load until after everything else has run.)

<script
  src="https://js.sentry-cdn.com/examplePublicKey.min.js"
  crossorigin="anonymous"
></script>

Loader Configuration

The loader has two configuration options:

• What version of the SDK to load
• When to load the SDK

SDK Version

To configure the version, use the dropdown in the JavaScript Loader settings, directly beneath the script tag you copied earlier.

Note that because of caching, it can take a few minutes for version changes made here to take effect.

Load Timing

By default, the loader won't load the full SDK until triggered by one of the following:

• an unhandled error
• an unhandled promise rejection
• a call to Sentry.captureMessage
• a call to Sentry.captureEvent

Once one of those occurs, the loader will buffer that event and immediately request the full SDK from our CDN. Any events that occur between that request being made and the completion of SDK initialization will also be buffered, and all buffered events will be sent to Sentry once the SDK is fully initialized.

Alternatively, you can set the loader to request the full SDK earlier: still as part of page load, but after all of the other JavaScript on the page has run. (In other words, in a subsequent event loop.) To do this, include data-lazy="no" in your script tag.

<script
  src="https://js.sentry-cdn.com/examplePublicKey.min.js"
  crossorigin="anonymous"
  data-lazy="no"
></script>

Finally, if you want to control the timing yourself, you can call Sentry.forceLoad(). You can do this as early as immediately after the loader runs (which has the same effect as setting data-lazy="no") and as late as the first unhandled error, unhandled promise rejection, or call to Sentry.captureMessage or Sentry.captureEvent (which has the same effect as not calling it at all). Note that you can't delay loading past one of the aforementioned triggering events.

SDK Configuration

The loader script includes a call to Sentry.init with one configuration option: your DSN. If you want to configure your SDK beyond that, you'll need a second script tag, in which you'll call Sentry.onLoad. This script must come after the main loader script.

<script
  src="https://js.sentry-cdn.com/examplePublicKey.min.js"
  crossorigin="anonymous"
></script>
<script>
  Sentry.onLoad(function() { ... });
</script>

Sentry.onLoad is a function that only the loader provides, and - as the name suggests - it sets a function to be run once the full SDK has been loaded. In that function, you can configure your SDK exactly the way you would were you using the CDN, with one difference: your Sentry.init call doesn't need to include your DSN, since it's already been set.

<script>
  Sentry.onLoad(function() {
    Sentry.init({
      release: " ... ",
      environment: " ... "
    });
    Sentry.configureScope(scope => {
      scope.setTag( ... );
    });
    // etc.
  });
</script>

Limitations

Because the loader injects the SDK asynchronously, only unhandled errors and unhandled promise rejections will be caught and buffered before the SDK is fully loaded. Specifically, the capturing of any breadcrumb data will not be available until the SDK is fully loaded and initialized. To reduce the amount of time these features are unavailable, set data-lazy="no" or call forceLoad() as described above.

For similar reasons, the loader is not available in a form which includes either performance monitoring or release health (sessions). If you want performance monitoring, including pageload times, you can our NPM package or use our CDN, specifically the bundle that includes tracing features. For release health, bundling is the only option, though no additional package is needed.

If you want to understand the inner workings of the loader itself, you can read the documented source code in all its glory over at the sentry-javascript repository.