feat(nextjs): added webpack treeshaking flags as config (#18359)

This PR updates the Sentry Next.js integration to improve tree-shaking
configuration and add new options for finer control over what SDK code
is included in the final bundle.

The most significant changes are:

- Added several new tree-shaking flags for better user DX.


Closes #18417

---------

Co-authored-by: Copilot <[email protected]>

Author: logaretm

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+- feat(nextjs): Add tree-shaking configuration to `webpack` build config ([#18359](https://github.com/getsentry/sentry-javascript/pull/18359))
+
 ## 10.31.0
 
 ### Important Changes

packages/nextjs/src/config/types.ts

@@ -112,6 +112,36 @@ export type SentryBuildWebpackOptions = {
      * Removes Sentry SDK logger statements from the bundle. Note that this doesn't affect Sentry Logs.
      */
     removeDebugLogging?: boolean;
+
+    /**
+     * Setting this to true will treeshake any SDK code that is related to tracing and performance monitoring.
+     */
+    removeTracing?: boolean;
+
+    /**
+     * Setting this flag to `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.
+     * This has no effect if you did not add `replayIntegration`.
+     */
+    excludeReplayIframe?: boolean;
+
+    /**
+     * Setting this flag to `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.
+     * This has no effect if you did not add `replayIntegration`.
+     */
+    excludeReplayShadowDOM?: boolean;
+
+    /**
+     * Setting this flag to `true` will tree shake any SDK code that is 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.
+     * This has no effect if you did not add `replayIntegration`.
+     */
+    excludeReplayCompressionWorker?: boolean;
   };
 
   /**
@@ -403,38 +433,38 @@ export type SentryBuildOptions = {
    */
   bundleSizeOptimizations?: {
     /**
-     * If set to `true`, the Sentry SDK will attempt to tree-shake (remove) any debugging code within itself during the build.
+     * If set to `true`, the Sentry SDK will attempt to treeshake (remove) any debugging code within itself during the build.
      * Note that the success of this depends on tree shaking being enabled in your build tooling.
      *
      * Setting this option to `true` will disable features like the SDK's `debug` option.
      */
     excludeDebugStatements?: boolean;
 
     /**
-     * If set to `true`, the Sentry SDK will attempt to tree-shake (remove) code within itself that is related to tracing and performance monitoring.
+     * If set to `true`, the Sentry SDK will attempt to treeshake (remove) code within itself that is related to tracing and performance monitoring.
      * Note that the success of this depends on tree shaking being enabled in your build tooling.
      * **Notice:** Do not enable this when you're using any performance monitoring-related SDK features (e.g. `Sentry.startTransaction()`).
      */
     excludeTracing?: boolean;
 
     /**
-     * If set to `true`, the Sentry SDK will attempt to tree-shake (remove) code related to the SDK's Session Replay Shadow DOM recording functionality.
+     * If set to `true`, the Sentry SDK will attempt to treeshake (remove) code related to the SDK's Session Replay Shadow DOM recording functionality.
      * Note that the success of this depends on tree shaking being enabled in your build tooling.
      *
      * This option is safe to be used when you do not want to capture any Shadow DOM activity via Sentry Session Replay.
      */
     excludeReplayShadowDom?: boolean;
 
     /**
-     * If set to `true`, the Sentry SDK will attempt to tree-shake (remove) code related to the SDK's Session Replay `iframe` recording functionality.
+     * If set to `true`, the Sentry SDK will attempt to treeshake (remove) code related to the SDK's Session Replay `iframe` recording functionality.
      * Note that the success of this depends on tree shaking being enabled in your build tooling.
      *
      * You can safely do this when you do not want to capture any `iframe` activity via Sentry Session Replay.
      */
     excludeReplayIframe?: boolean;
 
     /**
-     * If set to `true`, the Sentry SDK will attempt to tree-shake (remove) code related to the SDK's Session Replay's Compression Web Worker.
+     * If set to `true`, the Sentry SDK will attempt to treeshake (remove) code related to the SDK's Session Replay's Compression Web Worker.
      * Note that the success of this depends on tree shaking being enabled in your build tooling.
      *
      * **Notice:** You should only use this option if you manually host a compression worker and configure it in your Sentry Session Replay integration config via the `workerUrl` option.

packages/nextjs/src/config/webpack.ts

@@ -428,13 +428,8 @@ export function constructWebpackConfigFunction({
       }
     }
 
-    if (userSentryOptions.webpack?.treeshake?.removeDebugLogging) {
-      newConfig.plugins = newConfig.plugins || [];
-      newConfig.plugins.push(
-        new buildContext.webpack.DefinePlugin({
-          __SENTRY_DEBUG__: false,
-        }),
-      );
+    if (userSentryOptions.webpack?.treeshake) {
+      setupTreeshakingFromConfig(userSentryOptions, newConfig, buildContext);
     }
 
     // We inject a map of dependencies that the nextjs app has, as we cannot reliably extract them at runtime, sadly
@@ -912,3 +907,42 @@ function _getModules(projectDir: string): Record<string, string> {
     return {};
   }
 }
+
+/**
+ * Sets up the tree-shaking flags based on the user's configuration.
+ * https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/tree-shaking/
+ */
+function setupTreeshakingFromConfig(
+  userSentryOptions: SentryBuildOptions,
+  newConfig: WebpackConfigObjectWithModuleRules,
+  buildContext: BuildContext,
+): void {
+  const defines: Record<string, boolean> = {};
+
+  newConfig.plugins = newConfig.plugins || [];
+
+  if (userSentryOptions.webpack?.treeshake?.removeDebugLogging) {
+    defines.__SENTRY_DEBUG__ = false;
+  }
+
+  if (userSentryOptions.webpack?.treeshake?.removeTracing) {
+    defines.__SENTRY_TRACING__ = false;
+  }
+
+  if (userSentryOptions.webpack?.treeshake?.excludeReplayIframe) {
+    defines.__RRWEB_EXCLUDE_IFRAME__ = true;
+  }
+
+  if (userSentryOptions.webpack?.treeshake?.excludeReplayShadowDOM) {
+    defines.__RRWEB_EXCLUDE_SHADOW_DOM__ = true;
+  }
+
+  if (userSentryOptions.webpack?.treeshake?.excludeReplayCompressionWorker) {
+    defines.__SENTRY_EXCLUDE_REPLAY_WORKER__ = true;
+  }
+
+  // Only add DefinePlugin if there are actual defines to set
+  if (Object.keys(defines).length > 0) {
+    newConfig.plugins.push(new buildContext.webpack.DefinePlugin(defines));
+  }
+}

packages/nextjs/test/config/fixtures.ts

@@ -101,7 +101,9 @@ export function getBuildContext(
     } as NextConfigObject,
     webpack: {
       version: webpackVersion,
-      DefinePlugin: class {} as any,
+      DefinePlugin: class {
+        constructor(public definitions: Record<string, any>) {}
+      } as any,
       ProvidePlugin: class {
         constructor(public definitions: Record<string, any>) {}
       } as any,