feat(nextjs): Deprecate Webpack top-level options

packages/nextjs/src/config/getBuildPluginOptions.ts

@@ -205,7 +205,7 @@ function createReleaseConfig(
       vcsRemote: sentryBuildOptions.release?.vcsRemote,
       setCommits: sentryBuildOptions.release?.setCommits,
       deploy: sentryBuildOptions.release?.deploy,
-      ...sentryBuildOptions.unstable_sentryWebpackPluginOptions?.release,
+      ...sentryBuildOptions.webpack?.unstable_sentryWebpackPluginOptions?.release,
     };
   }
 
@@ -241,7 +241,7 @@ export function getBuildPluginOptions({
   const normalizedDistDirAbsPath = normalizePathForGlob(distDirAbsPath);
 
   const loggerPrefix = LOGGER_PREFIXES[buildTool];
-  const widenClientFileUpload = sentryBuildOptions.widenClientFileUpload ?? false;
+  const widenClientFileUpload = sentryBuildOptions.webpack?.widenClientFileUpload ?? false;
   const deleteSourcemapsAfterUpload = sentryBuildOptions.sourcemaps?.deleteSourcemapsAfterUpload ?? false;
 
   const sourcemapUploadAssets = createSourcemapUploadAssetPatterns(
@@ -272,8 +272,8 @@ export function getBuildPluginOptions({
     reactComponentAnnotation: buildTool.startsWith('after-production-compile')
       ? undefined
       : {
-          ...sentryBuildOptions.reactComponentAnnotation,
-          ...sentryBuildOptions.unstable_sentryWebpackPluginOptions?.reactComponentAnnotation,
+          ...sentryBuildOptions.webpack?.reactComponentAnnotation,
+          ...sentryBuildOptions.webpack?.unstable_sentryWebpackPluginOptions?.reactComponentAnnotation,
         },
     silent: sentryBuildOptions.silent,
     url: sentryBuildOptions.sentryUrl,
@@ -283,7 +283,7 @@ export function getBuildPluginOptions({
       assets: sentryBuildOptions.sourcemaps?.assets ?? sourcemapUploadAssets,
       ignore: sentryBuildOptions.sourcemaps?.ignore ?? sourcemapUploadIgnore,
       filesToDeleteAfterUpload,
-      ...sentryBuildOptions.unstable_sentryWebpackPluginOptions?.sourcemaps,
+      ...sentryBuildOptions.webpack?.unstable_sentryWebpackPluginOptions?.sourcemaps,
     },
     release: createReleaseConfig(releaseName, sentryBuildOptions),
     bundleSizeOptimizations: {
@@ -295,6 +295,6 @@ export function getBuildPluginOptions({
         metaFramework: 'nextjs',
       },
     },
-    ...sentryBuildOptions.unstable_sentryWebpackPluginOptions,
+    ...sentryBuildOptions.webpack?.unstable_sentryWebpackPluginOptions,
   };
 }

packages/nextjs/src/config/types.ts

@@ -57,6 +57,104 @@ export type NextConfigObject = {
   };
 };
 
+export type SentryBuildWebpackOptions = {
+  /**
+   * Include Next.js-internal code and code from dependencies when uploading source maps.
+   *
+   * Note: Enabling this option can lead to longer build times.
+   * Disabling this option will leave you without readable stacktraces for dependencies and Next.js-internal code.
+   *
+   * Defaults to `false`.
+   */
+  // Enabling this option may upload a lot of source maps and since the sourcemap upload endpoint in Sentry is super
+  // slow we don't enable it by default so that we don't opaquely increase build times for users.
+  // TODO: Add an alias to this function called "uploadSourceMapsForDependencies"
+  widenClientFileUpload?: boolean;
+
+  /**
+   * Automatically instrument Next.js data fetching methods and Next.js API routes with error and performance monitoring.
+   * Defaults to `true`.
+   */
+  autoInstrumentServerFunctions?: boolean;
+
+  /**
+   * Automatically instrument Next.js middleware with error and performance monitoring. Defaults to `true`.
+   */
+  autoInstrumentMiddleware?: boolean;
+
+  /**
+   * Automatically instrument components in the `app` directory with error monitoring. Defaults to `true`.
+   */
+  autoInstrumentAppDirectory?: boolean;
+
+  /**
+   * Automatically create cron monitors in Sentry for your Vercel Cron Jobs if configured via `vercel.json`.
+   *
+   * Defaults to `false`.
+   */
+  automaticVercelMonitors?: boolean;
+
+  /**
+   * Exclude certain serverside API routes or pages from being instrumented with Sentry during build-time. This option
+   * takes an array of strings or regular expressions. This options also affects pages in the `app` directory.
+   *
+   * NOTE: Pages should be specified as routes (`/animals` or `/api/animals/[animalType]/habitat`), not filepaths
+   * (`pages/animals/index.js` or `.\src\pages\api\animals\[animalType]\habitat.tsx`), and strings must be be a full,
+   * exact match.
+   *
+   * Notice: If you build Next.js with turbopack, the Sentry SDK will no longer apply build-time instrumentation and
+   * purely rely on Next.js telemetry features, meaning that this option will effectively no-op.
+   */
+  excludeServerRoutes?: Array<RegExp | string>;
+
+  /**
+   * Disables automatic injection of Sentry's Webpack configuration.
+   *
+   * By default, the Sentry Next.js SDK injects its own Webpack configuration to enable features such as
+   * source map upload and automatic instrumentation. Set this option to `true` if you want to prevent
+   * the SDK from modifying your Webpack config (for example, if you want to handle Sentry integration manually
+   * or if you are on an older version of Next.js while using Turbopack).
+   */
+  disableSentryConfig?: boolean;
+
+  /**
+   * Tree shakes Sentry SDK logger statements from the bundle.
+   */
+  treeshake?: {
+    /**
+     * Tree shakes Sentry SDK logger statements from the bundle. Note that this doesn't affect Sentry Logs.
+     */
+    debugLogs?: boolean;
+  };
+
+  /**
+   * Options to be passed directly to the Sentry Webpack Plugin (`@sentry/webpack-plugin`) that ships with the Sentry SDK.
+   * You can use this option to override any options the SDK passes to the Webpack plugin.
+   *
+   * Please note that this option is unstable and may change in a breaking way in any release.
+   */
+  unstable_sentryWebpackPluginOptions?: SentryWebpackPluginOptions;
+
+  /**
+   * Options related to react component name annotations.
+   * Disabled by default, unless a value is set for this option.
+   * When enabled, your app's DOM will automatically be annotated during build-time with their respective component names.
+   * This will unlock the capability to search for Replays in Sentry by component name, as well as see component names in breadcrumbs and performance monitoring.
+   * Please note that this feature is not currently supported by the esbuild bundler plugins, and will only annotate React components
+   */
+  reactComponentAnnotation?: {
+    /**
+     * Whether the component name annotate plugin should be enabled or not.
+     */
+    enabled?: boolean;
+
+    /**
+     * A list of strings representing the names of components to ignore. The plugin will not apply `data-sentry` annotations on the DOM element for these components.
+     */
+    ignoredComponents?: string[];
+  };
+};
+
 export type SentryBuildOptions = {
   /**
    * The slug of the Sentry organization associated with the app.
@@ -363,6 +461,8 @@ export type SentryBuildOptions = {
    * When enabled, your app's DOM will automatically be annotated during build-time with their respective component names.
    * This will unlock the capability to search for Replays in Sentry by component name, as well as see component names in breadcrumbs and performance monitoring.
    * Please note that this feature is not currently supported by the esbuild bundler plugins, and will only annotate React components
+   *
+   * @deprecated Use `webpack.reactComponentAnnotation` instead.
    */
   reactComponentAnnotation?: {
     /**
@@ -381,6 +481,7 @@ export type SentryBuildOptions = {
    * You can use this option to override any options the SDK passes to the webpack plugin.
    *
    * Please note that this option is unstable and may change in a breaking way in any release.
+   * @deprecated Use `webpack.unstable_sentryWebpackPluginOptions` instead.
    */
   unstable_sentryWebpackPluginOptions?: SentryWebpackPluginOptions;
 
@@ -391,6 +492,7 @@ export type SentryBuildOptions = {
    * Disabling this option will leave you without readable stacktraces for dependencies and Next.js-internal code.
    *
    * Defaults to `false`.
+   * @deprecated Use `webpack.widenClientFileUpload` instead.
    */
   // Enabling this option may upload a lot of source maps and since the sourcemap upload endpoint in Sentry is super
   // slow we don't enable it by default so that we don't opaquely increase build times for users.
@@ -400,16 +502,19 @@ export type SentryBuildOptions = {
   /**
    * Automatically instrument Next.js data fetching methods and Next.js API routes with error and performance monitoring.
    * Defaults to `true`.
+   * @deprecated Use `webpack.autoInstrumentServerFunctions` instead.
    */
   autoInstrumentServerFunctions?: boolean;
 
   /**
    * Automatically instrument Next.js middleware with error and performance monitoring. Defaults to `true`.
+   * @deprecated Use `webpack.autoInstrumentMiddleware` instead.
    */
   autoInstrumentMiddleware?: boolean;
 
   /**
    * Automatically instrument components in the `app` directory with error monitoring. Defaults to `true`.
+   * @deprecated Use `webpack.autoInstrumentAppDirectory` instead.
    */
   autoInstrumentAppDirectory?: boolean;
 
@@ -423,6 +528,8 @@ export type SentryBuildOptions = {
    *
    * Notice: If you build Next.js with turbopack, the Sentry SDK will no longer apply build-time instrumentation and
    * purely rely on Next.js telemetry features, meaning that this option will effectively no-op.
+   *
+   * @deprecated Use `webpack.excludeServerRoutes` instead.
    */
   excludeServerRoutes?: Array<RegExp | string>;
 
@@ -439,13 +546,17 @@ export type SentryBuildOptions = {
 
   /**
    * Tree shakes Sentry SDK logger statements from the bundle.
+   *
+   * @deprecated Use `webpack.treeshake.debugLogs` instead.
    */
   disableLogger?: boolean;
 
   /**
    * Automatically create cron monitors in Sentry for your Vercel Cron Jobs if configured via `vercel.json`.
    *
    * Defaults to `false`.
+   *
+   * @deprecated Use `webpack.automaticVercelMonitors` instead.
    */
   automaticVercelMonitors?: boolean;
 
@@ -497,6 +608,8 @@ export type SentryBuildOptions = {
    * the SDK from modifying your Webpack config (for example, if you want to handle Sentry integration manually
    * or if you are on an older version of Next.js while using Turbopack).
    *
+   * @deprecated Use `webpack.disableSentryConfig` instead.
+   *
    * @default false
    */
   disableSentryWebpackConfig?: boolean;
@@ -519,6 +632,11 @@ export type SentryBuildOptions = {
   _experimental?: Partial<{
     thirdPartyOriginStackFrames?: boolean;
   }>;
+
+  /**
+   * Options related to webpack builds, has no effect if you are using Turbopack.
+   */
+  webpack?: SentryBuildWebpackOptions;
 };
 
 export type NextConfigFunction = (

packages/nextjs/src/config/webpack.ts

@@ -145,7 +145,7 @@ export function constructWebpackConfigFunction({
       appDir: appDirPath,
       pagesDir: pagesDirPath,
       pageExtensionRegex,
-      excludeServerRoutes: userSentryOptions.excludeServerRoutes,
+      excludeServerRoutes: userSentryOptions.webpack?.excludeServerRoutes,
       nextjsRequestAsyncStorageModulePath: getRequestAsyncStorageModuleLocation(
         projectDir,
         rawNewConfig.resolve?.modules,
@@ -220,7 +220,7 @@ export function constructWebpackConfigFunction({
       );
     };
 
-    if (isServer && userSentryOptions.autoInstrumentServerFunctions !== false) {
+    if (isServer && userSentryOptions.webpack?.autoInstrumentServerFunctions !== false) {
       // It is very important that we insert our loaders at the beginning of the array because we expect any sort of transformations/transpilations (e.g. TS -> JS) to already have happened.
 
       // Wrap pages
@@ -239,7 +239,7 @@ export function constructWebpackConfigFunction({
 
       let vercelCronsConfig: VercelCronsConfig = undefined;
       try {
-        if (process.env.VERCEL && userSentryOptions.automaticVercelMonitors) {
+        if (process.env.VERCEL && userSentryOptions.webpack?.automaticVercelMonitors) {
           // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
           vercelCronsConfig = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'vercel.json'), 'utf8')).crons;
           if (vercelCronsConfig) {
@@ -277,7 +277,7 @@ export function constructWebpackConfigFunction({
 
       // Wrap middleware
       const canWrapStandaloneMiddleware = userNextConfig.output !== 'standalone' || !major || major < 16;
-      if ((userSentryOptions.autoInstrumentMiddleware ?? true) && canWrapStandaloneMiddleware) {
+      if ((userSentryOptions.webpack?.autoInstrumentMiddleware ?? true) && canWrapStandaloneMiddleware) {
         newConfig.module.rules.unshift({
           test: isMiddlewareResource,
           use: [
@@ -293,7 +293,7 @@ export function constructWebpackConfigFunction({
       }
     }
 
-    if (isServer && userSentryOptions.autoInstrumentAppDirectory !== false) {
+    if (isServer && userSentryOptions.webpack?.autoInstrumentAppDirectory !== false) {
       // Wrap server components
       newConfig.module.rules.unshift({
         test: isServerComponentResource,
@@ -431,7 +431,7 @@ export function constructWebpackConfigFunction({
       }
     }
 
-    if (userSentryOptions.disableLogger) {
+    if (userSentryOptions.webpack?.treeshake?.debugLogs) {
       newConfig.plugins = newConfig.plugins || [];
       newConfig.plugins.push(
         new buildContext.webpack.DefinePlugin({