Tree Shaking

The Sentry SDK supports tree shaking in various ways. To fully utilize the tree shaking capabilities of modern bundlers like webpack or Rollup, some additional configurations must be applied. If you want to minimize the bundle size of the Sentry SDK, we recommend reading through this page and applying the tree shaking configurations as shown.

Tree Shaking Optional Code

The Sentry SDK ships with code that is not strictly required for it to collect your errors. This includes code to debug your Sentry configuration or code to enable performance monitoring, for example. While debug code can be very useful in development environments, it's not typically necessary to include it in your production bundles where it takes up valuable space. The JavaScript SDK includes special flags in its CommonJS and ESM distributions, which can be used to facilitate tree shaking (removal) of this kind of code during the build process.

Tree Shaking With Sentry Bundler Plugins

This configuration is available starting with v2.9.0 of the bundler plugins.

If you're using one of our bundler plugins, you can use the bundleSizeOptimizations configuration option to tree shake optional code:

// For example, the @sentry/webpack-plugin passed to the webpack config
sentryPlugin({
  // other config
  bundleSizeOptimizations: {
    excludeDebugStatements: true,
    excludePerformanceMonitoring: true,
    excludeReplayIframe: true,
    excludeReplayShadowDom: true,
    excludeReplayWorker: true,
  },
});

For more details, see the documentation for the specific bundler plugin you're using:

• Sentry Webpack Plugin
• Sentry Vite Plugin
• Sentry Esbuild Plugin
• Sentry Rollup Plugin

Manual Tree Shaking

If you want to tree shake optional code, remove the code from your build output by replacing various flags in the Sentry SDK.

The following flags are available:

__SENTRY_DEBUG__

Replacing this flag with false will tree shake any SDK code that's related to debug logging.

__SENTRY_TRACING__

Replacing this flag with false will tree shake any SDK code that's related to performance monitoring.

__RRWEB_EXCLUDE_IFRAME__

Replacing this flag with true will tree shake any SDK code related to capturing iframe content with Session Replay. It's only relevant when using Session Replay. Enable this flag if you don't want to record any iframes.

__RRWEB_EXCLUDE_SHADOW_DOM__

Replacing this flag with true will tree shake any SDK code related to capturing shadow dom elements with Session Replay. It's only relevant when using Session Replay. Enable this flag if you don't want to record any shadow dom elements.

__SENTRY_EXCLUDE_REPLAY_WORKER__

Replacing this flag with true will tree shake any SDK code that's related to the included compression web worker for Session Replay. It's only relevant when using Session Replay. Enable this flag if you want to host a compression worker yourself. See Using a Custom Compression Worker for details. We don't recommend enabling this flag unless you provide a custom worker URL.

Tree Shaking With Webpack

To tree shake Sentry debug code in your webpack bundles, we recommend using webpack's DefinePlugin:

const webpack = require("webpack");

module.exports = {
  // ... other options
  plugins: [
    new webpack.DefinePlugin({
      __SENTRY_DEBUG__: false,
      __SENTRY_TRACING__: false,
      __RRWEB_EXCLUDE_IFRAME__: true,
      __RRWEB_EXCLUDE_SHADOW_DOM__: true,
      __SENTRY_EXCLUDE_REPLAY_WORKER__: true,
    }),
    // ... other plugins
  ],
};

Tree Shaking With Rollup

If you're using rollup.js, we recommend using Rollup's replace plugin:

import replace from "@rollup/plugin-replace";
import { terser } from "rollup-plugin-terser";

export default {
  // ... other options
  treeshake: "smallest", // recommended for best tree shaking results
  plugins: [
    replace({
      __SENTRY_DEBUG__: false,
      __SENTRY_TRACING__: false,
      __RRWEB_EXCLUDE_IFRAME__: true,
      __RRWEB_EXCLUDE_SHADOW_DOM__: true,
      __SENTRY_EXCLUDE_REPLAY_WORKER__: true,
    }),
    // ... other plugins (best placed after)
  ],
};

Tree Shaking Default Integrations

By default, the Sentry SDK sets up a list of default integrations that extend your SDK functionality. You can also add additional or custom integrations to your SDK configuration. If you don't want to include default integrations in your config, you can disable them and add your custom array of integrations. However, if you also want to tree shake the unused default integrations, you can do so by creating a Client yourself. By doing this, you essentially bypass Sentry.init which normally creates a Client for you.

The following example shows how to create and bind a Client which enables tree shaking of unused default integrations:

import {
  BrowserClient,
  breadcrumbsIntegration,
  dedupeIntegration,
  defaultStackParser,
  getCurrentScope,
  globalHandlersIntegration,
  makeFetchTransport,
  linkedErrorsIntegration,
} from "@sentry/browser";

const client = new BrowserClient({
  // all options you normally pass to Sentry.init
  dsn: "your DSN",
  // ...
  transport: makeFetchTransport,
  stackParser: defaultStackParser,
  // Only the integrations listed here will be used
  integrations: [
    breadcrumbsIntegration(),
    globalHandlersIntegration(),
    linkedErrorsIntegration(),
    dedupeIntegration(),
  ],
});

getCurrentScope().setClient(client);
client.init();