feat(nextjs): Promote useRunAfterProductionCompileHook to non-experimental build option (#17721)

Author: chargome

packages/nextjs/src/config/types.ts

@@ -501,22 +501,23 @@ export type SentryBuildOptions = {
    */
   disableSentryWebpackConfig?: boolean;
 
+  /**
+   * When true (and Next.js >= 15), use the runAfterProductionCompile hook to consolidate sourcemap uploads
+   * into a single operation after builds complete, reducing build time.
+   *
+   * When false, use the traditional approach of uploading sourcemaps during each webpack build. For Turbopack no sourcemaps will be uploaded.
+   *
+   * @default false
+   */
+  useRunAfterProductionCompileHook?: boolean;
+
   /**
    * Contains a set of experimental flags that might change in future releases. These flags enable
    * features that are still in development and may be modified, renamed, or removed without notice.
    * Use with caution in production environments.
    */
   _experimental?: Partial<{
-    /**
-     * When true (and Next.js >= 15), use the runAfterProductionCompile hook to consolidate sourcemap uploads
-     * into a single operation after turbopack builds complete, reducing build time.
-     *
-     * When false, use the traditional approach of uploading sourcemaps during each webpack build.
-     *
-     * @default false
-     */
-    useRunAfterProductionCompileHook?: boolean;
-    thirdPartyOriginStackFrames: boolean;
+    thirdPartyOriginStackFrames?: boolean;
   }>;
 };
 

packages/nextjs/src/config/withSentryConfig.ts

@@ -294,7 +294,7 @@ function getFinalConfigObject(
     }
   }
 
-  if (userSentryOptions?._experimental?.useRunAfterProductionCompileHook === true && supportsProductionCompileHook()) {
+  if (userSentryOptions?.useRunAfterProductionCompileHook === true && supportsProductionCompileHook()) {
     if (incomingUserNextConfigObject?.compiler?.runAfterProductionCompile === undefined) {
       incomingUserNextConfigObject.compiler ??= {};
       incomingUserNextConfigObject.compiler.runAfterProductionCompile = async ({ distDir }) => {
@@ -379,7 +379,7 @@ function getFinalConfigObject(
             releaseName,
             routeManifest,
             nextJsVersion,
-            useRunAfterProductionCompileHook: userSentryOptions._experimental?.useRunAfterProductionCompileHook,
+            useRunAfterProductionCompileHook: userSentryOptions?.useRunAfterProductionCompileHook,
           }),
     ...(isTurbopackSupported && isTurbopack
       ? {

packages/nextjs/test/config/testUtils.ts

@@ -77,8 +77,7 @@ export async function materializeFinalWebpackConfig(options: {
     routeManifest: options.routeManifest,
     nextJsVersion: options.nextJsVersion,
     useRunAfterProductionCompileHook:
-      options.useRunAfterProductionCompileHook ??
-      options.sentryBuildTimeOptions?._experimental?.useRunAfterProductionCompileHook,
+      options.useRunAfterProductionCompileHook ?? options.sentryBuildTimeOptions?.useRunAfterProductionCompileHook,
   });
 
   // call it to get concrete values for comparison

packages/nextjs/test/config/webpack/constructWebpackConfig.test.ts

@@ -100,9 +100,7 @@ describe('constructWebpackConfigFunction()', () => {
       incomingWebpackConfig: serverWebpackConfig,
       incomingWebpackBuildContext: serverBuildContext,
       sentryBuildTimeOptions: {
-        _experimental: {
-          useRunAfterProductionCompileHook: true,
-        },
+        useRunAfterProductionCompileHook: true,
       },
     });
 
@@ -128,9 +126,7 @@ describe('constructWebpackConfigFunction()', () => {
       incomingWebpackConfig: serverWebpackConfig,
       incomingWebpackBuildContext: serverBuildContext,
       sentryBuildTimeOptions: {
-        _experimental: {
-          useRunAfterProductionCompileHook: false,
-        },
+        useRunAfterProductionCompileHook: false,
       },
     });
 

packages/nextjs/test/config/withSentryConfig.test.ts

@@ -769,27 +769,27 @@ describe('withSentryConfig', () => {
       vi.restoreAllMocks();
     });
 
-    it('sets up runAfterProductionCompile hook when experimental flag is enabled and version is supported', () => {
+    it('sets up runAfterProductionCompile hook when flag is enabled and version is supported', () => {
       vi.spyOn(util, 'supportsProductionCompileHook').mockReturnValue(true);
 
       const sentryOptions = {
-        _experimental: {
-          useRunAfterProductionCompileHook: true,
-        },
+        useRunAfterProductionCompileHook: true,
       };
 
-      const finalConfig = materializeFinalNextConfig(exportedNextConfig, undefined, sentryOptions);
+      // Use a clean copy of the config to avoid test interference
+      const cleanConfig = { ...exportedNextConfig };
+      delete cleanConfig.compiler;
+
+      const finalConfig = materializeFinalNextConfig(cleanConfig, undefined, sentryOptions);
 
       expect(finalConfig.compiler?.runAfterProductionCompile).toBeInstanceOf(Function);
     });
 
-    it('does not set up hook when experimental flag is disabled', () => {
+    it('does not set up hook when flag is disabled', () => {
       vi.spyOn(util, 'supportsProductionCompileHook').mockReturnValue(true);
 
       const sentryOptions = {
-        _experimental: {
-          useRunAfterProductionCompileHook: false,
-        },
+        useRunAfterProductionCompileHook: false,
       };
 
       const cleanConfig = { ...exportedNextConfig };
@@ -804,9 +804,7 @@ describe('withSentryConfig', () => {
       vi.spyOn(util, 'supportsProductionCompileHook').mockReturnValue(false);
 
       const sentryOptions = {
-        _experimental: {
-          useRunAfterProductionCompileHook: true,
-        },
+        useRunAfterProductionCompileHook: true,
       };
 
       const cleanConfig = { ...exportedNextConfig };
@@ -829,9 +827,7 @@ describe('withSentryConfig', () => {
       };
 
       const sentryOptions = {
-        _experimental: {
-          useRunAfterProductionCompileHook: true,
-        },
+        useRunAfterProductionCompileHook: true,
       };
 
       const finalConfig = materializeFinalNextConfig(configWithExistingHook, undefined, sentryOptions);
@@ -852,9 +848,7 @@ describe('withSentryConfig', () => {
       };
 
       const sentryOptions = {
-        _experimental: {
-          useRunAfterProductionCompileHook: true,
-        },
+        useRunAfterProductionCompileHook: true,
       };
 
       materializeFinalNextConfig(configWithInvalidHook, undefined, sentryOptions);
@@ -873,9 +867,7 @@ describe('withSentryConfig', () => {
       delete configWithoutCompiler.compiler;
 
       const sentryOptions = {
-        _experimental: {
-          useRunAfterProductionCompileHook: true,
-        },
+        useRunAfterProductionCompileHook: true,
       };
 
       const finalConfig = materializeFinalNextConfig(configWithoutCompiler, undefined, sentryOptions);
@@ -890,126 +882,35 @@ describe('withSentryConfig', () => {
       vi.spyOn(util, 'supportsProductionCompileHook').mockReturnValue(true);
 
       const sentryOptions = {
-        _experimental: {
-          useRunAfterProductionCompileHook: true,
-        },
-      };
-
-      const finalConfig = materializeFinalNextConfig(exportedNextConfig, undefined, sentryOptions);
-
-      expect(finalConfig.compiler?.runAfterProductionCompile).toBeInstanceOf(Function);
-
-      delete process.env.TURBOPACK;
-    });
-
-    it('works with webpack builds when TURBOPACK env is not set', () => {
-      delete process.env.TURBOPACK;
-      vi.spyOn(util, 'supportsProductionCompileHook').mockReturnValue(true);
-
-      const sentryOptions = {
-        _experimental: {
-          useRunAfterProductionCompileHook: true,
-        },
-      };
-
-      const finalConfig = materializeFinalNextConfig(exportedNextConfig, undefined, sentryOptions);
-
-      expect(finalConfig.compiler?.runAfterProductionCompile).toBeInstanceOf(Function);
-    });
-  });
-
-  describe('experimental flag handling', () => {
-    afterEach(() => {
-      vi.restoreAllMocks();
-    });
-
-    it('respects useRunAfterProductionCompileHook: true', () => {
-      vi.spyOn(util, 'supportsProductionCompileHook').mockReturnValue(true);
-
-      const sentryOptions = {
-        _experimental: {
-          useRunAfterProductionCompileHook: true,
-        },
+        useRunAfterProductionCompileHook: true,
       };
 
+      // Use a clean copy of the config to avoid test interference
       const cleanConfig = { ...exportedNextConfig };
       delete cleanConfig.compiler;
 
       const finalConfig = materializeFinalNextConfig(cleanConfig, undefined, sentryOptions);
 
       expect(finalConfig.compiler?.runAfterProductionCompile).toBeInstanceOf(Function);
-    });
 
-    it('respects useRunAfterProductionCompileHook: false', () => {
-      vi.spyOn(util, 'supportsProductionCompileHook').mockReturnValue(true);
-
-      const sentryOptions = {
-        _experimental: {
-          useRunAfterProductionCompileHook: false,
-        },
-      };
-
-      const cleanConfig = { ...exportedNextConfig };
-      delete cleanConfig.compiler;
-
-      const finalConfig = materializeFinalNextConfig(cleanConfig, undefined, sentryOptions);
-
-      expect(finalConfig.compiler?.runAfterProductionCompile).toBeUndefined();
-    });
-
-    it('does not set up hook when experimental flag is undefined', () => {
-      vi.spyOn(util, 'supportsProductionCompileHook').mockReturnValue(true);
-
-      const sentryOptions = {
-        _experimental: {
-          // useRunAfterProductionCompileHook not specified
-        },
-      };
-
-      const cleanConfig = { ...exportedNextConfig };
-      delete cleanConfig.compiler;
-
-      const finalConfig = materializeFinalNextConfig(cleanConfig, undefined, sentryOptions);
-
-      expect(finalConfig.compiler?.runAfterProductionCompile).toBeUndefined();
+      delete process.env.TURBOPACK;
     });
 
-    it('does not set up hook when _experimental is undefined', () => {
+    it('works with webpack builds when TURBOPACK env is not set', () => {
+      delete process.env.TURBOPACK;
       vi.spyOn(util, 'supportsProductionCompileHook').mockReturnValue(true);
 
       const sentryOptions = {
-        // no _experimental property
+        useRunAfterProductionCompileHook: true,
       };
 
+      // Use a clean copy of the config to avoid test interference
       const cleanConfig = { ...exportedNextConfig };
       delete cleanConfig.compiler;
 
       const finalConfig = materializeFinalNextConfig(cleanConfig, undefined, sentryOptions);
 
-      expect(finalConfig.compiler?.runAfterProductionCompile).toBeUndefined();
-    });
-
-    it('combines experimental flag with other configurations correctly', () => {
-      process.env.TURBOPACK = '1';
-      vi.spyOn(util, 'getNextjsVersion').mockReturnValue('15.4.1');
-      vi.spyOn(util, 'supportsProductionCompileHook').mockReturnValue(true);
-
-      const sentryOptions = {
-        _experimental: {
-          useRunAfterProductionCompileHook: true,
-        },
-        sourcemaps: {},
-        tunnelRoute: '/tunnel',
-      };
-
-      const finalConfig = materializeFinalNextConfig(exportedNextConfig, undefined, sentryOptions);
-
-      // Should have both turbopack sourcemap config AND runAfterProductionCompile hook
-      expect(finalConfig.productionBrowserSourceMaps).toBe(true);
       expect(finalConfig.compiler?.runAfterProductionCompile).toBeInstanceOf(Function);
-      expect(finalConfig.rewrites).toBeInstanceOf(Function);
-
-      delete process.env.TURBOPACK;
     });
   });
 });