Loader Script

The Loader Script is the easiest way to initialize the Sentry SDK. The Loader Script also automatically keeps your Sentry SDK up to date and offers configuration for different Sentry features.

Using the Loader

To use the loader, go in the Sentry UI to Settings > Projects > (select project) > 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.

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

By default, Performance Monitoring and Session Replay is enabled.

Source Maps

To have correct stack traces for minified asset files when using the Loader Script, you will have to upload & host your Source Maps publicly.

Loader Configuration

The loader has a few configuration options:

  • What version of the SDK to load
  • Using Performance Monitoring
  • Using Session Replay
  • Showing debug logs

SDK Version

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

JavaScript Loader Settings

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

Load Timing

If you only use the Loader for errors, 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.captureException
  • 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.

Copied
<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.

If Performance Monitoring and/or Session Replay is enabled, the SDK will immediately fetch and initialize the bundle to make sure it can capture transactions and/or replays once the page loads.

SDK Configuration

You can configure the release by adding the following to your page:

Copied
<script>
  window.SENTRY_RELEASE = {
    id: "...",
  };
</script>

The loader script always includes a call to Sentry.init with a default configuration, including 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.

Copied
<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.

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

For Performance Monitoring, by default, the SDK will be initialized with tracesSampleRate: 1. This means that the SDK will capture all traces.

For Session Replay, the defaults are set to replaysSessionSampleRate: 0.1 and replaysOnErrorSampleRate: 1. This means Replays will be captured for 10% of all normal sessions and for all sessions with an error.

Limitations of error-only capturing

When using the Loader Script with just errors, the script injects the SDK asynchronously. This means that only unhandled errors and unhandled promise rejections will be caught and buffered before the SDK is fully loaded. Specifically, capturing 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.

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 repository.

CDN

Sentry supports loading the JavaScript SDK from a CDN. Generally we suggest using our Loader instead. If you must use a CDN, see Available Bundles below.

Default Bundle

To use Sentry for error and performance monitoring, you can use the following bundle:

Copied
<script
  src="https://browser.sentry-cdn.com/7.54.0/bundle.tracing.min.js"
  integrity="sha384-+h0OKHbAGUGuqyOQt8GPxoAlivqJAJnscoCE5ftl2SV77nWLjqoXvT4p6QLPjEh1"
  crossorigin="anonymous"
></script>

Performance & Replay Bundle

To use Sentry for error and performance monitoring, as well as for Session Replay, you can use the following bundle:

Copied
<script
  src="https://browser.sentry-cdn.com/7.54.0/bundle.tracing.replay.min.js"
  integrity="sha384-8wl63sykJEt5wJGcyNxwRPnLlRq8LtOMYzWhhRmdZS2PeYLAkgr8ILtC5ns+akjI"
  crossorigin="anonymous"
></script>

Errors & Replay Bundle

To use Sentry for error monitoring, as well as for Session Replay, but not for performance monitoring, you can use the following bundle:

Copied
<script
  src="https://browser.sentry-cdn.com/7.54.0/bundle.replay.min.js"
  integrity="sha384-mur1t1nxhVOuLo/E1tqu7PimEJ5w3qt7Zv0myoJ+zfALlLhIgTCP1zMgKLxriW8H"
  crossorigin="anonymous"
></script>

Errors-only Bundle

If you only use Sentry for error monitoring, and don't need performance

tracingThe process of logging the events that took place during a request, often across multiple services.
or replay functionality, you can use the following bundle:

Copied
<script
  src="https://browser.sentry-cdn.com/7.54.0/bundle.min.js"
  integrity="sha384-EmlJLN9Q0yu0/2UUCIYnEM88jpQ7xUhtNI2ZeXb/ci3cwoAoIQl350N4PQPlMbP5"
  crossorigin="anonymous"
></script>

Usage & Configuration

Once you've included the Sentry SDK bundle in your page, you can use Sentry in your own bundle:

Copied
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  // this assumes your build process replaces `process.env.npm_package_version` with a value
  release: "my-project-name@" + process.env.npm_package_version,
  integrations: [
    // If you use a bundle with performance monitoring enabled, add the BrowserTracing integration
    new Sentry.BrowserTracing({
      // Set `tracePropagationTargets` to control for which URLs distributed tracing should be enabled
      tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/],
    }),
    // If you use a bundle with session replay enabled, add the SessionReplay integration
    new Sentry.Replay(),
  ],

  // We recommend adjusting this value in production, or using tracesSampler
  // for finer control
  tracesSampleRate: 1.0,
});

Available Bundles

Our CDN hosts a variety of bundles:

  • @sentry/browser with error monitoring only (named bundle.<modifiers>.js)
  • @sentry/browser with error and performance monitoring (named bundle.tracing.<modifiers>.js)
  • @sentry/browser with error and session replay (named bundle.replay.<modifiers>.js)
  • @sentry/browser with error, performance monitoring and session replay (named bundle.tracing.replay.<modifiers>.js)
  • each of the integrations in @sentry/integrations (named <integration-name>.<modifiers>.js)

Each bundle is offered in both ES6 and ES5 versions. Since v7 of the SDK, the bundles are ES6 by default. To use the ES5 bundle, add the .es5 modifier.

Each version has three bundle varieties:

  • minified (.min)
  • unminified (no .min), includes debug logging
  • minified with debug logging (.debug.min)

Bundles that include debug logging output more detailed log messages, which can be helpful for debugging problems. Make sure to enable debug to see debug messages in the console. Unminified and debug logging bundles have a greater bundle size than minified ones.

For example:

  • bundle.js is @sentry/browser, compiled to ES6 but not minified, with debug logging included (as it is for all unminified bundles)
  • rewriteframes.es5.min.js is the RewriteFrames integration, compiled to ES5 and minified, with no debug logging
  • bundle.tracing.es5.debug.min.js is @sentry/browser with performance monitoring enabled, compiled to ES5 and minified, with debug logging included
FileIntegrity Checksum
bundle.debug.min.jssha384-R7Ad0sQHya0cdRoaPGgK/Tdf73DDtFBUgkifgVt5UvLXteUkDACoYuNwehxiJAc/
bundle.es5.debug.min.jssha384-KrJm1pw+PCEp4CHLLU+mxbC1STYsW6hExz0bwyA60NBQR4HcCvPIh1cJnsU56/vV
bundle.es5.jssha384-Q1Cr/ho8RRCEl2bzUE0DZZnVp/bDo4PePZpb52uFCdwjWnzluPhpeZH4Qa/yRX4M
bundle.es5.min.jssha384-Jpd6LzJxu0WsHGsdtjOD3GLEuMACoFl+NwPqAw1z5LVkS+eJBIG1ITQyiN8O/abQ
bundle.jssha384-JYNq81WSNpbb1aRGhWR80PD1pm60v/41Gj6HTHkRt+BW23Es7UVRX7+Flr8JgSGl
bundle.min.jssha384-EmlJLN9Q0yu0/2UUCIYnEM88jpQ7xUhtNI2ZeXb/ci3cwoAoIQl350N4PQPlMbP5
bundle.replay.debug.min.jssha384-vRGcA+EB+q1hZ8do4qRFvIBy1rGayrDsEYogvIOGtHX7CszE2J0xeR8aTCfHoBRQ
bundle.replay.jssha384-IoqxaFDgHnXZ6EjZH2Gv0CWZE8NbYh5NPhKinRDUqsAumefsAcBgHAkocIXYPy3v
bundle.replay.min.jssha384-mur1t1nxhVOuLo/E1tqu7PimEJ5w3qt7Zv0myoJ+zfALlLhIgTCP1zMgKLxriW8H
bundle.tracing.debug.min.jssha384-vC6uUvIabE1oxJ2U/V6/M8COS+cmz72nzlmOalSbasQscJ8b2LZ5sfA+PfJW8W3u
bundle.tracing.es5.debug.min.jssha384-9dbcidja8JIGGJtiERR8epCEOsqSucDxngsXwq/ocLebGw1b4hg/AOQKO6dQMsL6
bundle.tracing.es5.jssha384-2rDBqTVo1WXoxwIwrY76ZpGMpOp0WxIAviiAakvyUuyKKo+KUlictuuBe87nhMk6
bundle.tracing.es5.min.jssha384-GcCSjQPQq3VAuAtoSMXh1zumgntaB/di+e/+WMoKyFPKacseXJReJe8o/+fhJZRl
bundle.tracing.jssha384-5hqtXEBV4JRxBHV+z7TB59//CA/qcTbGK57iqQyMi50v4e7hMhLIRXxYrWrSywKy
bundle.tracing.min.jssha384-+h0OKHbAGUGuqyOQt8GPxoAlivqJAJnscoCE5ftl2SV77nWLjqoXvT4p6QLPjEh1
bundle.tracing.replay.debug.min.jssha384-xU5lIYTLNkf/crAcCjuV30ITHJV881RFS3zon1qcKgGzv41W18ozLJYUKXaZe+P0
bundle.tracing.replay.jssha384-cV5sFBTTDQsvCEd72MFq6p8rGmD390lS9J5KDm5I1RcbZJj82w2JH+JdYgawYQkI
bundle.tracing.replay.min.jssha384-8wl63sykJEt5wJGcyNxwRPnLlRq8LtOMYzWhhRmdZS2PeYLAkgr8ILtC5ns+akjI
captureconsole.debug.min.jssha384-rSZHrk+jXRP5zSrUrmIStuwLhOWwACxjlrf/dE8NKHtN2P66rl8ViPRBGWIMIxYK
captureconsole.es5.debug.min.jssha384-E9KDeUpbwNOUYOXxU0GyOb9N79ae+JT9CZYBSHC8kVuBdIm7cM53th7H0TEM16Vl
captureconsole.es5.jssha384-xGer96x+KTkJlkgCEBQp56Elo5ibB7v7hZEsc3QAYJUxa3rLlo1VRuSrIyOk4lCV
captureconsole.es5.min.jssha384-KIiC23UkSbzUJuGYN00nlAW02aLzMbV7HXi04mYJLO6qxrtXS4XwokYBJhUxCPn1
captureconsole.jssha384-LCDw5COOhJdCGugCn+dcP7MeR+9zZUhpawbFUlsDs0IpvY5QwLQ8mh69V6XC2v5h
captureconsole.min.jssha384-V6ZvJlQ8y5xx82GkSzpKcRIgWVOAioJf0ObTuguNAg4liORrTqSpGqlfPXP5pvEn
debug.debug.min.jssha384-WIYjXRbaahNCr0wy1PKB/TV1ja79wpedPYfWtkg/VazoA498lmvEK/3OdniKDU8v
debug.es5.debug.min.jssha384-MDgtVWkFzPXe+p1D/gbeCkA4Evjfcxi4PxDueBGAPx7xAE2K3VghfZ9+QOwjiChk
debug.es5.jssha384-6rYSAOaTOqZUPrvCpeTQteV8o6J9gPLSgFRxKr+b11bLTLuB2dCpqI9i3xfqbjxk
debug.es5.min.jssha384-0XGnf9ui7RzZ05wGoNW5BK8/hK8zT8gEHCre/8XE95EMlCuhhZl5aGkwxWTcK45n
debug.jssha384-PXHpyp5ifOyNO31B1yx/Wr+rg9HSI2C6oa4fq/NmjlEfFnN60vyZQu9tiH+sfp3o
debug.min.jssha384-9RtXi8dPjrdYWry6ZDeqWiLvinbpwqFWcml71zsR1SAsFvdRG0EnWhBDDuzHnyKU
dedupe.debug.min.jssha384-cMeOYGH6b0EY8I/q1lEjw/kXirgBARDT9T/jdfd9aFWmkJUdvmCCo0ia5RPDpqIx
dedupe.es5.debug.min.jssha384-CROQ1Pu7W/J8q/5ZMsGbyCnApcIwcJ0yIBd00aYYJNmZkh6ONMd0KFLl1zgkFkuO
dedupe.es5.jssha384-H6bsDfFrnrLOB+5V2gMHrt+QOvmuqZ5IeBK3ya3MxoiCg3nMjkots6N6OxqL8b4f
dedupe.es5.min.jssha384-Rrs5xM4UpQFzWbGnIyMVqoyW6v56MbXuOtWCtV1Xsf7MyHjNuEA1ofzdI7fIJtFv
dedupe.jssha384-ex61iaK6OfqAHxKx3K9jb5AZo+FzYrcjP4E9HYDR4EUela2Kl98IH8GHvz78Ewjc
dedupe.min.jssha384-GCqnaziSbnI1dHtRiYPxmtdgjtrlJHhP9IOyfWn5r1kuSV4aUOkgn4ciHM3IsiQw
extraerrordata.debug.min.jssha384-3OQc2AbKcCF0xJSwS0gGZFSa6DnBLjrcK/Oobm17xyjluMNOzMplgWDy3anjzs56
extraerrordata.es5.debug.min.jssha384-foT6VqOfeCvNlS+wE4QPmTtCsPrLcaipIytCQzoVJxtPkgmP9sZmWpJTNNJx6WtZ
extraerrordata.es5.jssha384-vFcmi5a/yyBRKHv35RQEl0i+VaPJxaRcMKL0ynV8v+Mm4o3qnp85scLAP2WWlUk2
extraerrordata.es5.min.jssha384-b+E1IAw9smr+KZXBfqFqXTaQElRG7gfIDwvhWsgg8dchrIWzGJvwortEOaJt2/rb
extraerrordata.jssha384-fi2d9ABIq5gkahdfAEsdXiMB7EenZBICEn3r76dA9+wp/dQLp5dWbj6vyTHXTjru
extraerrordata.min.jssha384-S3K/loKg2kem6WVdy90v6EpCv8fuehB3TrJtBQaGRIqEa9ABNmz49hWOXZ8RY+W0
httpclient.debug.min.jssha384-+gSmciPXvDvKsN+XcD9xf5YgqdVEkgDhvkpGwBQDUAr0Uc/CZ0V/Sx3akjJgoSGv
httpclient.es5.debug.min.jssha384-5+224gVtX0RS+IWkaIFnHosdk56n1x1eWRT3ldPf3dwZacU9DebEV7YHuZycVTIa
httpclient.es5.jssha384-AcVhYwPOpK4YHo4XCDbfNeAMF2NM088z5ycPs0q5YZcxV/XXrUaiobQ8nW8TVn4r
httpclient.es5.min.jssha384-b3n9kcRgiui8uU9TBl5E3bmhsD9r+j7QszDfzHT3HKmgJzHnT1p77nk0ERVzibl8
httpclient.jssha384-/ur5zzdlbOvQ3kiZHeoWgJDu8tTp5TiHfl8uZw6TreuvVfmLAZeznqGwsriGHfe+
httpclient.min.jssha384-DP3v9+dqIQ6IzH8K3kZzUQXmR2x+LhnNxTJUoX4WPO73s2kXFC2aN7WjY+KSoKk7
offline.debug.min.jssha384-qKSFGUpmFSPMjPda5IZ8leRTFbIpsH6K6mJz6ojz4W+iRan1y5mkND+y1T6z+SBG
offline.es5.debug.min.jssha384-AJXa1PGumqz6YeLBRle6QuPHfufkvxXZvcrRhm3ImwLzRD1mGgDaTk5xxLkTY88K
offline.es5.jssha384-9pbG2W+EG/2nh168/ADfNRsxL7iH8lrXU+wxPJ6DvJYJPkvLqwwuYb7Xdn/e43gC
offline.es5.min.jssha384-nc/VH3rcsZPKa/pvYVDcu7wyi4aGKxyu4aqw3ZFBTfbX4XdbBt/mA8Bn9X+fF9jD
offline.jssha384-cyWupoXVgWEnJT7PAHTQ+KkGHOkgwCh43UPcaEeQlImjg9saaMnjlorldr3UuB4H
offline.min.jssha384-SnAbAu6cu770Hel19cYT1KMHdrIrseFCY2Y/SJBodmFcN6hDFyPkzG7khe5xYQsz
replay.debug.min.jssha384-+5eFp989Ivt8suXpoaziEoifpNE1/VkFJ98DHkeJBuOXubgp4R77zojPrdKPgEvS
replay.jssha384-m8kM6GLN5x5NIxktY+Qylc3aMJSyX1ZDnqHb09K2dnDX/eSCHMAxFJ8GdTpJTMpZ
replay.min.jssha384-nOsmsGr7pB8NMBwj238K7qhL8kvXVv3IBQF8PK+0jcIegdUgywT/P2PYyOb7xZfl
reportingobserver.debug.min.jssha384-NyQPX7npOsMbO9byGo7ZZ/RWLYFxJ/G3HZMOhCkccuBwNirvj8nfevnUBhGYG+gO
reportingobserver.es5.debug.min.jssha384-e1/Y5YQ1pbLREzU0b5T0Tx/kaBLEwPvSY0IefJFZIXkv/nrQviqld17CdSO7012P
reportingobserver.es5.jssha384-sJpCnBJytuNbdMMjZ5I6wv+lMu+k3kI9pNK8dwgUcPFKMNAzaHZne7JE+tPfIGbr
reportingobserver.es5.min.jssha384-nkJ/F6KFoxGRXrWrZZlVQRkMrW4SlPZGvZrgdleGd1LnRPr5RJOa/JDBbbCpUnsp
reportingobserver.jssha384-YSNz8jd4FEljonwsnJCa4O64rbdsZKf7qrp/XdjYXDs27ZAezWtUVhxWGnxA7cdL
reportingobserver.min.jssha384-5sK2QzTYdoWmphLFvbtAyjr114/2T7ygv7LsVqw74ytLdKp8LQb6IyEU9GqbEAYe
rewriteframes.debug.min.jssha384-IpcAnrxTbqqGzsr/vkR2AKBeWHjd6FU9ExPTch5V7IoxtbuboUMRnjDQBUomdYls
rewriteframes.es5.debug.min.jssha384-Mt+6J2safDOInNwstqY1OfOaaYu7bET163S3f06jhTO/AjqXzUHIcJu3zIWBTODr
rewriteframes.es5.jssha384-gISpZxfLdkB3SVrMx9LcPXzW77hlFtMeDyoyTrS1UPAh0ihC15FzcG/K4RQNsG5q
rewriteframes.es5.min.jssha384-UBisVjErxfBnIcN+BjpOPKdhw+b+XZyJgaFdaOekw4uts7Eeg9RbGmJfw1VZHkQD
rewriteframes.jssha384-qmEVi/YwhEcGd1ZtyY+pjyeqtcoF6DbG1jypmfMnZzxWq/BFdGMQz7DlaKpZKuW0
rewriteframes.min.jssha384-26zl9hp8INPLSppnOxlWUv6+E48x5BAGWN6JFFns5ZkHNP483l7X9EaiWXODL4ur
sessiontiming.debug.min.jssha384-jqwklCtBZtsA90DYvfRdEU/2GvwSeV2sFGMxf9BLB7pEkAinQo/5jiCxTHPPSl5U
sessiontiming.es5.debug.min.jssha384-jYTNX8d7DlEB0Z2I0WOKmyxUYTCJhXXMqc/eskarZHfjlW23rtpnMcOrlC5qHiQP
sessiontiming.es5.jssha384-YgB+Dyh97/R8OGhIt8YQFJGn7ckeVk+3SM5xLVrOUsDXLg5YjbWZy9w9kqTE824R
sessiontiming.es5.min.jssha384-SeLOrPZl01g80LQf78betnAj/vvCW4OKLEx9Kbh4d+crGe6d5HCS0m4hQN8Dv2bl
sessiontiming.jssha384-GIPMIaOebcRwUVFvvD7fxxEpzHWx1QhPAhhKwddhPwubjP64RLsUWXI274Sbzgw8
sessiontiming.min.jssha384-g0DmXJTy7eVsVUISXegoDGS1J0PT+ADV80nyItnF5eNTUsb0+UMgHZNfdVPnEV/e
transaction.debug.min.jssha384-gFrOcnDzZvvz5UVY+ruza0Y5gp+IrO0Wch7gjNwxI0EgI84VqXbxzPRDQ7xgb0Yg
transaction.es5.debug.min.jssha384-5LtSDUYMb4rKANkaVwuEMDZBK0f8h7AoSX/Eo+I6+//IXXTNmMF1/iwiIFZKX32+
transaction.es5.jssha384-q4kizHheR9Urn6GeOarV+uOZSBpkQm2ZDrus6FWno2k0YFybKedI/2pI0B00eJu7
transaction.es5.min.jssha384-suFJOmiDLW60UoMhEvNTOLWnrEy9j3i+7IRPTjaEkTketiKNuJP31+T/h/z54ha+
transaction.jssha384-5FHyhsh3bS/9+lF3JBPJmrgD5fUPJFCItmXxgHr5z+RFLakX/NRZAZgnjg/dsHtK
transaction.min.jssha384-q3WZuBH/Fs5CuYq85dzI1tlEqe1VDnWjPughxKBda3RlOG9vun9Z3MeX9bGn0lzQ

Additional Configuration

Using defer

If you use the defer script attribute, we strongly recommend that you place the script tag for the browser SDK first and mark all of your other scripts with defer (but not async). This will guarantee that that the Sentry SDK is executed before any of the others.

Without doing this you will find that it's possible for errors to occur before Sentry is loaded, which means you'll be flying blind to those issues.

Content Security Policy

If you have a Content Security Policy (CSP) set up on your site, you will need to add the script-src of wherever you're loading the SDK from, and the origin of your DSN. For example:

  • script-src: https://browser.sentry-cdn.com https://js.sentry-cdn.com
  • connect-src: *.sentry.io
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").