Loader Script

Learn about the Sentry JavaScript 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.

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, Tracing and Session Replay are enabled.

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

The loader has a few configuration options:

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

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.

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

While the Loader Script will work out of the box without any configuration in your application, you can still configure the SDK according to your needs.

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

For Session Replay, the defaults are 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.

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 can configure a custom init call by defining a window.sentryOnLoad function. Whatever is defined inside of this function will always be called first, before any other SDK method is called.

Be sure to define this function before you add the loader script, to ensure it can be called at the right time:

Copied
<script>
  // Configure sentryOnLoad before adding the Loader Script
  window.sentryOnLoad = function () {
    Sentry.init({
      // add custom config here
    });
  };
</script>

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

Inside of the window.sentryOnLoad function, you can configure a custom Sentry.init() call. You can configure your SDK exactly the way you would if you were using the CDN, with one difference: your Sentry.init() call doesn't need to include your DSN, since it's already been set. Inside of this function, the full Sentry SDK is guaranteed to be loaded & available.

Copied
<script>
  // Configure sentryOnLoad before adding the Loader Script
  window.sentryOnLoad = function () {
    Sentry.init({
      release: " ... ",
      environment: " ... "
    });
    Sentry.setTag(...);
    // etc.
  };
</script>

By default, the loader will make sure you can call these functions directly on Sentry at any time, even if the SDK is not yet loaded:

  • Sentry.captureException()
  • Sentry.captureMessage()
  • Sentry.captureEvent()
  • Sentry.addBreadcrumb()
  • Sentry.withScope()
  • Sentry.showReportDialog()

If you want to call any other method when using the Loader, you have to guard it with Sentry.onLoad(). Any callback given to onLoad() will be called either immediately (if the SDK is already loaded), or later once the SDK has been loaded:

Copied
<script>
  window.sentryOnLoad = function () {
    Sentry.init({
      // ...
    });
  };
</script>

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

<script>
  // Guard against window.Sentry not being available, e.g. due to Ad-blockers
  window.Sentry &&
    Sentry.onLoad(function () {
      // Inside of this callback,
      // we guarantee that `Sentry` is fully loaded and all APIs are available
      const client = Sentry.getClient();
      // do something custom here
    });
</script>

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.

Because the loader script injects the actual SDK asynchronously to keep your pageload performance high, the SDK's tracing functionality is only available once the SDK is loaded and initialized. This means that if you e.g. have fetch calls right at the beginning of your application, they might not be traced. If this is a critical issue for you, you have two options to ensure that all your fetch calls are traced:

  • Initialize the SDK in window.sentryOnLoad as described in Custom Configuration. Then make your fetch call in the Sentry.onload callback.
    Example
    Copied
    <script>
      window.sentryOnLoad = function () {
        Sentry.init({
          // ...
        });
      };
    </script>
    
    <script
      src="https://js.sentry-cdn.com/examplePublicKey.min.js"
      crossorigin="anonymous"
    ></script>
    
    <script>
      Sentry.onLoad(function () {
        fetch("/api/users");
      });
    </script>
    
  • Use the CDN bundles instead of the Loader Script. This will ensure that the SDK is loaded synchronously, and that all your fetch calls are traced.

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.

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

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

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

Copied
<script
  src="https://browser.sentry-cdn.com/9.25.0/bundle.tracing.replay.min.js"
  integrity="sha384-LUWByxH+kcVL0nPxkVPsh0n2NNXjf88UomOku/35L9izBsygJ9MpVIRJJAWV+3U1"
  crossorigin="anonymous"
></script>

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

Copied
<script
  src="https://browser.sentry-cdn.com/9.25.0/bundle.replay.min.js"
  integrity="sha384-u67CQugAMqIf1YFHDpJv2tdcHGCRHupS1tEqhxE2EoHk7jSi5r6qBFmdYAPT5H5k"
  crossorigin="anonymous"
></script>

If you only use Sentry for error monitoring, and don't need performance tracing or replay functionality, you can use the following bundle:

Copied
<script
  src="https://browser.sentry-cdn.com/9.25.0/bundle.min.js"
  integrity="sha384-g9POgKT+opD6/2dJc83hmSXC+rPmhPCi+ZNFDefZbO3lLiuumZlAiCUKsPzFTuXc"
  crossorigin="anonymous"
></script>

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 tracing enabled, add the BrowserTracing integration
    Sentry.browserTracingIntegration(),
    // If you use a bundle with session replay enabled, add the Replay integration
    Sentry.replayIntegration(),
  ],

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

  // Set `tracePropagationTargets` to control for which URLs distributed tracing should be enabled
  tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/],
});

Our CDN hosts a variety of bundles:

  • @sentry/browser with error monitoring only (named bundle.<modifiers>.js)
  • @sentry/browser with error and tracing (named bundle.tracing.<modifiers>.js)
  • @sentry/browser with error and session replay (named bundle.replay.<modifiers>.js)
  • @sentry/browser with error, tracing 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 tracing enabled, compiled to ES5 and minified, with debug logging included
FileIntegrity Checksum
browserprofiling.debug.min.jssha384-xeGnS5e1z3kYjNqhqRDhdTce4LIgjbjIkc3NgeXL9ChDITVNmRVdcj5tf8qTi3yJ
browserprofiling.jssha384-iswfvVSGCjEmtDc6SV6UjGIt0+8GMBUe+WzIbSFn6pdGQ3phkREpj/x3HWwAi8xo
browserprofiling.min.jssha384-3/qtM7Hy6j3I3IKf+br1wST/BtHWzFYMICNYROei6wQf01RMI/6xQ5vSFtXOWlMp
bundle.debug.min.jssha384-Qy04Ubpoyb3R8hbTvX4GMww4HQquIcYM+vSRTkxstC4hhdrJC+oIIaIDnYLkvjkY
bundle.feedback.debug.min.jssha384-VkEFnNkZfZJK1bQ68lygg72zbMIUDJ7+Jikf77GxkNcmJ6YNHxAKMzcdwIU0YfMD
bundle.feedback.jssha384-rMQXxmioM6WPQqXC4UAxszbemrvNwHIAhGELC4q4hOq4lpF2s1y1cM+MyeBA+URm
bundle.feedback.min.jssha384-irEJpOTlNldpbQrcb8HGk4CcxsW0NZXM6jd83K4jW+y3psW7CVgKLIae03pkabI9
bundle.jssha384-z9o/fDqr0+UWAcVmEKTY5WxYzPZYLeiekurSTkC/Ev02Qry/S9R9f5vAs9UkUGDz
bundle.min.jssha384-g9POgKT+opD6/2dJc83hmSXC+rPmhPCi+ZNFDefZbO3lLiuumZlAiCUKsPzFTuXc
bundle.replay.debug.min.jssha384-fJUnosmPC2g0UC2nR4wd+jIZXdwjKEfqO5F+rLzhQwVzQiT6JcyvrkVgOEBs66nM
bundle.replay.jssha384-ClF6eLjx0Ry6LMWLfwUQCcnnQ5/fH6s+vxObOBuCqoCZt0tGfwOCgVfzC3rzQp42
bundle.replay.min.jssha384-u67CQugAMqIf1YFHDpJv2tdcHGCRHupS1tEqhxE2EoHk7jSi5r6qBFmdYAPT5H5k
bundle.tracing.debug.min.jssha384-M4Oy8vfC8xWQ1GPHYGc3xQp/BHU218eoTuYkA1rytVy9X2k4mrJhms/7kZcnPcxi
bundle.tracing.jssha384-8QPjfr+NPt02j+PRvCxfR923gJySQoZfNjit1fsYRb2uc+mL1JnqxYIBRvtdTldx
bundle.tracing.min.jssha384-TqnzYyb10q72vFD7NsxCanjTKx8tS5dWMEQCOIJ/CjQeuMwUOvIfuZcdplXQe2Nd
bundle.tracing.replay.debug.min.jssha384-j1/TU2wK8mV2WqgC8X8QitsvkCdzrpT8cJYyVgmHoITsh1LUVkgxg81MpqcJB2+4
bundle.tracing.replay.feedback.debug.min.jssha384-wbn35WRVpNzgRxL2hiBvuk7PF/DLyupITBRzbWaRs1yS8vIwrJ9zcM7slJ3k4DNL
bundle.tracing.replay.feedback.jssha384-fq2SV6I0myfrFhjBEuJNdtgU2uoEDkgFDKDVito7YbBni+6mhhM6gw8Fm8DgNPZ2
bundle.tracing.replay.feedback.min.jssha384-Rg6xomGipP6UjnD7QPu89mMDh4n9RanrQi6CMhMBgW4wD8GnRYFfN6agSqytT+So
bundle.tracing.replay.jssha384-yp3U5EMVMiZ2/4/ktPntWnj9jJGdKVLk8EWA/YV9WHh9JT2sFDqYERJmYmCfS6av
bundle.tracing.replay.min.jssha384-LUWByxH+kcVL0nPxkVPsh0n2NNXjf88UomOku/35L9izBsygJ9MpVIRJJAWV+3U1
captureconsole.debug.min.jssha384-27Ywx03iwXEqROyPRsA94o+lYN533cgXV27b3VwNvH3kMkHVDMlXDgZ3EE7JQcRj
captureconsole.jssha384-OrrBb3oCNYNMgqk6S9dDRCLGRmUBZynR+dAUJdRTn0D/61IxYpNxao+E2EtKI0SM
captureconsole.min.jssha384-J9TJeiyJth34Sd0p84g1Bjk2wrePAwAoieDNvXTHTfv1MepgwoanXiGW36FaZrO9
contextlines.debug.min.jssha384-sgdAJp9aGWk8+RCh9r4gw4hw1rHaHbTsed3dJPEcTtZoVqIv+e+H9ZRRLc5sml9/
contextlines.jssha384-+oqwy9cxVkuWZ/G8Yn1cOud5VsIY4jL7vMQHNjwtsPJaYvY5xNo5siv1sKH6wZPo
contextlines.min.jssha384-Eesfxm/6FYz0P4HdN+hYgT+VUr81JQrCNBB5nES0Bvp9uGWBtEUTtKyQRkrlD5QH
dedupe.debug.min.jssha384-C0EMULrpHDo0x/wQCLyZo9QzWQRIoMtqV2QQFkxS4wNZhltO6FT0LZ6x7XZGAjvr
dedupe.jssha384-dBS4XuSdsYlmJ0UYpgqApxn6/sCwCxmDlD7SVpAJQh/uBbir7JMft1N0DV/V/89Y
dedupe.min.jssha384-OxTNmYzYK6aeQwmZPuPI7q7XGSZTjtEGMbcRDIXKN6Yi4mjR+8I3DMQNPG+qQ4nL
extraerrordata.debug.min.jssha384-bU7hqFolHglLiv6e1XP3m/rDe2acHR7gr6l6y33XJXu36qfqb2lAVb72/dSjrLNA
extraerrordata.jssha384-kh/fwrE5TGVq6qpUk4ta4Qo/PMWxVKqTzoHbvVRcQV99QLSyj3kRi4q4Impqk9fK
extraerrordata.min.jssha384-7jDFZKNX98iI4MH9hcZr1OEaDomJyGBIJBKy1dHXD736xrSD4zYd/5g4IAfF6MjL
feedback-modal.debug.min.jssha384-7Mt0j4EjR8EMIT7nLH/f6Zre6+6bg2BHS0jpvxkXLaIHVccAv9WLgAFmYRoFDxOY
feedback-modal.jssha384-yDHzezb1PxPPkeQVLhZhgEA679JG0aeZX5jTH5RTMgsnKqUIFWLbEfqgnLntredk
feedback-modal.min.jssha384-qHpBgo4DKrcE76QghkyWsUUD/smuMJ9vSH/oJhzLVq0w5OHZKIzXTvXwaHNLUnWe
feedback-screenshot.debug.min.jssha384-zR+vvhsyUfFNr3ZCchWkTojsm5poXWn54eXCJ9QedH30ayt/tBNRwC0jGkejlv50
feedback-screenshot.jssha384-+xcUyY1M1drQJUOt+Jo5G8clgGHOObRq1i5fdNvE+27n9uxqY1gGv4zGsr3IPuhj
feedback-screenshot.min.jssha384-oQmtBD4fLxw5D90SPcvTU+qTIKUyopKFajRMVs0oHoWhjwIpB7/UMZxgws0uYnoo
feedback.debug.min.jssha384-Ryd4E8ghfWT6gCHWtnh5Jm/V2DAQ2rXWVZbXP2R5tGjuOux3JF5JDTe7bsPP6l/D
feedback.jssha384-bmYNAbR/kNwo6selLZGWxudTaWVY+1+RcTPvwihakqgleC+icrvy3PhYPrd79xqO
feedback.min.jssha384-o9zdOtaSMD6KkbEQk/ZH9gqbMfpjpzPA4yBJ7x/4Dz99jWjDHU3MH9bzpRvmFa7+
graphqlclient.debug.min.jssha384-wKtLXJ2M71s+k8M1LPsEjuZDuN6nkDtmcntkrEDe71t22s43di/xpvMwQ1XSiCZi
graphqlclient.jssha384-xluDyrqemEHY9rFIHd5ovAzSk3+jXvspZmqDOahhKwJKki2lsd27AcP+lLiFy+md
graphqlclient.min.jssha384-tHqEy92FMl0D/rXjwjhp6QmLtnr+8L6asId8jyGGRMXRy9Z1LGSfn3egLTvvtfUG
httpclient.debug.min.jssha384-gwDItXciZyynNo/pKlbTaI1zDm7HswHtt0f8FD+96q3Dg5AvDDCUrmYIm/YH6ACG
httpclient.jssha384-b1tPgafhf9Ti44bXIt9DflZ0/J2mz1e9N+jj7imyD6rUlNsyBrEzWGDXj/YU7xVa
httpclient.min.jssha384-tFEXzNVivMBIRUfUMsVfhBHK6J1qbgTrXtLbTZifH4MKWQbqsYfYJioR6TVIPssJ
modulemetadata.debug.min.jssha384-aBh3yQLfSq2b99zLiNjHHuyQdLynsX+y/FJCNHOO7Q1APMhDypjaTGRGHV1dqJVr
modulemetadata.jssha384-ulaE0j/M0iBtIVzb8dVJFoqsv3/uSlATgFCiL31onGliQARxPccmEgijjGiRx8ed
modulemetadata.min.jssha384-jeG011vhulpHCi+fL8GX+JS2F6Yl6Fcwd0x0a0hrEkjhfho+kCZ49wHDUV36xT3c
multiplexedtransport.debug.min.jssha384-wZdgnJh6S+aCa5KDiYDP5m3jCG7JRjKXGwH1T2zHv3c7agWf7qZwY13pbHRx6bzP
multiplexedtransport.jssha384-Cag1N19wIjVk01k7UWwzLVPN94RBLvZzYqc0NADcxjubRp0olP/7enRf+hmgt1zg
multiplexedtransport.min.jssha384-1pWlnCmVktClSvK5LnNGZBYCYMlakyyisGjkphOmiOT6S94AIE1zn1S3gM90YYwx
replay-canvas.debug.min.jssha384-t978MzE0ZfH/IiemzjeiEpbAaQylGn7d6zQlRDCJXXNJQPRlxwp6pz/Zzt9oM3TX
replay-canvas.jssha384-OgMkhV+FRtbO5ZG2rBhwatgxB7kaZ+vrGQzAU2WubkUyf6N+F9C92zoLUYcHiEo4
replay-canvas.min.jssha384-jtCMZT7uEvUi+TDyRzbSYSiXoZCVc7ZPZLjlWwJQ87ik/UE5OaRjgB5T0DN1gJlb
replay.debug.min.jssha384-I+LExyefTP/vJvdWnJk/U9hfvWwnTz5qmmM42vBUMk84IoIfwtgXwj/zq3miXX5V
replay.jssha384-4bP3nwARss17+r6eOm7dhM/ze6C4VKyMIjP35Yab+fgbCRPYtAKec+SyVqam0bs+
replay.min.jssha384-2i5pmX1KIKxPiDMedNd5VHzydJJq8P9OjZfAEiP422hSQaPnFeCkzlrBlmk+G+av
reportingobserver.debug.min.jssha384-d4FcZ/vi3S0R+hp085V4lF9wX8bnjq8R8ajMj+RBzCCEr7RErFffEvcHITK0Eno7
reportingobserver.jssha384-n+TMwh6iS2wTUuJcPbgnyvgO48kmtM7ho9yX1RJJ+25KpY0Ik58Ji2mB8b3EETff
reportingobserver.min.jssha384-1rdpswjTsw/iFk/xGBP6ZOis0WelvDsbMA1f5sQu7CpRdGKyvjNNJ/FEX8a9iLLD
rewriteframes.debug.min.jssha384-uD2iL3JI0PcQ2zhPf8e2VgWzGKGTzu/50h5ASwUHKBXHG1sv+Ma5OqrLjZa4tFVF
rewriteframes.jssha384-5BfuRgx/3TZXKV/JPRWph0bOwYZBWThvbTPlpPKNbdQrCZ2/HhxWqErD8Ie1Eaui
rewriteframes.min.jssha384-PbKmZ+EE1bVLA51ByNtSO74ZRXSxc71eaKxiHw9jWsZFS1eqS2EP337Zx1EC4621
spotlight.debug.min.jssha384-AfR8aDUS0/a18ShTx0slLmo/32a636JQgQzGEu5WkhfdG3TvVJJrnFq8zoyle4R6
spotlight.jssha384-EqVahXcpSnz6SORufgrwP9Owr/IPepDDwS1U16hFEzzs8mNAGInLM9iGtIWyxVDU
spotlight.min.jssha384-Sp2fLif/8CJezuR8hH1hmQoZIGl2zReTzZqolzhjbx+bvftj3nea5FxAkc7m0olq

To find the integrity hashes for older SDK versions, you can view our SDK release registry for the Browser SDK here.

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.

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
Was this helpful?
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").