fix(nextjs): Skip re instrumentating on generate phase of experimental build mode (#16410)

Next.js v15.3.0-canary.1 introduced a new approach to the two-phase
experimental build (--experimental-build-mode=compile then =generate)
that applies env inlining during generate build mode.
 
Why it breaks?
Our `withSentryConfig` still assumes a single “full” build and reruns
its Webpack instrumentation in both phases. During the generate step it
collides with Next.js’s new inliner (e.g. for assetPrefix), producing
malformed JS and build failures.

Root cause: Double application of build-time transforms—Sentry
inlines/reprocesses a bundle that Next.js’s generate mode is
simultaneously trying to finalize—leads to conflicting replacements and
syntax errors.

This PR is a quick workaround that patches our build script so that:
1. Compile phase (--experimental-build-mode=compile): Sentry’s
instrumentation runs as usual.
2. Generate phase (--experimental-build-mode=generate): We skip Sentry’s
build-time hooks entirely, letting Next.js handle inlining and
prerendering without collision.

This immediately prevents the build failures and defers full “generate”
work to Next.js’s own pipeline. I confirmed that source maps and error /
tracing still function as expected, BUT things might still occur as it's
still an experimental undocumented feature.

---------

Co-authored-by: Charly Gomez <[email protected]>

Author: RulaKhaled

packages/nextjs/src/config/withSentryConfig.ts

@@ -15,6 +15,7 @@ import { getNextjsVersion } from './util';
 import { constructWebpackConfigFunction } from './webpack';
 
 let showedExportModeTunnelWarning = false;
+let showedExperimentalBuildModeWarning = false;
 
 /**
  * Modifies the passed in Next.js configuration with automatic build-time instrumentation and source map upload.
@@ -67,6 +68,27 @@ function getFinalConfigObject(
     }
   }
 
+  if (process.argv.includes('--experimental-build-mode')) {
+    if (!showedExperimentalBuildModeWarning) {
+      showedExperimentalBuildModeWarning = true;
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[@sentry/nextjs] The Sentry Next.js SDK does not currently fully support next build --experimental-build-mode',
+      );
+    }
+    if (process.argv.includes('generate')) {
+      // Next.js v15.3.0-canary.1 splits the experimental build into two phases:
+      // 1. compile: Code compilation
+      // 2. generate: Environment variable inlining and prerendering (We don't instrument this phase, we inline in the compile phase)
+      //
+      // We assume a single “full” build and reruns Webpack instrumentation in both phases.
+      // During the generate step it collides with Next.js’s inliner
+      // producing malformed JS and build failures.
+      // We skip Sentry processing during generate to avoid this issue.
+      return incomingUserNextConfigObject;
+    }
+  }
+
   setUpBuildTimeVariables(incomingUserNextConfigObject, userSentryOptions, releaseName);
 
   const nextJsVersion = getNextjsVersion();

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

@@ -50,4 +50,29 @@ describe('withSentryConfig', () => {
 
     expect(exportedNextConfigFunction).toHaveBeenCalledWith(defaultRuntimePhase, defaultsObject);
   });
+
+  it('handles experimental build mode correctly', () => {
+    const originalArgv = process.argv;
+    const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    try {
+      process.argv = [...originalArgv, '--experimental-build-mode'];
+      materializeFinalNextConfig(exportedNextConfig);
+
+      expect(consoleWarnSpy).toHaveBeenCalledWith(
+        '[@sentry/nextjs] The Sentry Next.js SDK does not currently fully support next build --experimental-build-mode',
+      );
+
+      // Generate phase
+      process.argv = [...process.argv, 'generate'];
+      const generateConfig = materializeFinalNextConfig(exportedNextConfig);
+
+      expect(generateConfig).toEqual(exportedNextConfig);
+
+      expect(consoleWarnSpy).toHaveBeenCalledTimes(1);
+    } finally {
+      process.argv = originalArgv;
+      consoleWarnSpy.mockRestore();
+    }
+  });
 });