fix(nextjs): Handle Spotlight auto-enablement in Next.js client SDK

The browser SDK's Spotlight auto-detection is wrapped in rollup-include-development-only,
which strips it from production builds. Since users install production builds from npm,
the Next.js SDK needs to handle Spotlight auto-enablement explicitly.

This moves the Spotlight env var detection from the browser SDK to the Next.js client SDK,
which reads the injected NEXT_PUBLIC_SENTRY_SPOTLIGHT value from globalThis and adds the
Spotlight integration when appropriate.

This also avoids the issue where CI sets VITE_SENTRY_SPOTLIGHT=true globally, which was
accidentally enabling Spotlight in all test apps and potentially causing timing issues.

Author: BYK

packages/browser/src/sdk.ts

@@ -96,12 +96,8 @@ export function init(options: BrowserOptions = {}): Client | undefined {
   let defaultIntegrations =
     options.defaultIntegrations == null ? getDefaultIntegrations(options) : options.defaultIntegrations;
 
-  // Resolve Spotlight configuration with proper precedence.
-  // This code is intentionally NOT wrapped in rollup-include-development-only because:
-  // - Users install production builds of the SDK from npm
-  // - They expect auto-enablement to work during their app's development
-  // - The env var (NEXT_PUBLIC_SENTRY_SPOTLIGHT, etc.) won't be set in production deployments
-  // - Users can explicitly disable with `spotlight: false` if needed
+  /* rollup-include-development-only */
+  // Resolve Spotlight configuration with proper precedence
   const envSpotlight = getSpotlightConfig();
   // resolveSpotlightOptions is the single source of truth that ensures empty strings are never used
   const spotlightValue = resolveSpotlightOptions(options.spotlight, envSpotlight);
@@ -113,6 +109,7 @@ export function init(options: BrowserOptions = {}): Client | undefined {
     const args = typeof spotlightValue === 'string' ? { sidecarUrl: spotlightValue } : undefined;
     defaultIntegrations.push(spotlightBrowserIntegration(args));
   }
+  /* rollup-include-development-only-end */
 
   const clientOptions: BrowserClientOptions = {
     ...options,

packages/nextjs/src/client/index.ts

@@ -2,9 +2,21 @@
 // can be removed once following issue is fixed: https://github.com/import-js/eslint-plugin-import/issues/703
 /* eslint-disable import/export */
 import type { Client, EventProcessor, Integration } from '@sentry/core';
-import { addEventProcessor, applySdkMetadata, consoleSandbox, getGlobalScope, GLOBAL_OBJ } from '@sentry/core';
+import {
+  addEventProcessor,
+  applySdkMetadata,
+  consoleSandbox,
+  envToBool,
+  getGlobalScope,
+  GLOBAL_OBJ,
+  resolveSpotlightOptions,
+} from '@sentry/core';
 import type { BrowserOptions } from '@sentry/react';
-import { getDefaultIntegrations as getReactDefaultIntegrations, init as reactInit } from '@sentry/react';
+import {
+  getDefaultIntegrations as getReactDefaultIntegrations,
+  init as reactInit,
+  spotlightBrowserIntegration,
+} from '@sentry/react';
 import { devErrorSymbolicationEventProcessor } from '../common/devErrorSymbolicationEventProcessor';
 import { getVercelEnv } from '../common/getVercelEnv';
 import { isRedirectNavigationError } from '../common/nextNavigationErrorUtils';
@@ -31,6 +43,7 @@ const globalWithInjectedValues = GLOBAL_OBJ as typeof GLOBAL_OBJ & {
   _sentryBasePath?: string;
   _sentryRelease?: string;
   _experimentalThirdPartyOriginStackFrames?: string;
+  NEXT_PUBLIC_SENTRY_SPOTLIGHT?: string;
 };
 
 // Treeshakable guard to remove all code related to tracing
@@ -130,11 +143,24 @@ function getDefaultIntegrations(options: BrowserOptions): Integration[] {
     }),
   );
 
-  // Note: Spotlight auto-enablement from NEXT_PUBLIC_SENTRY_SPOTLIGHT is handled by the
-  // browser SDK's init() function. The Next.js build config injects the env var value via:
-  // - Webpack: DefinePlugin replaces process.env.NEXT_PUBLIC_SENTRY_SPOTLIGHT
+  // Add Spotlight integration if enabled via NEXT_PUBLIC_SENTRY_SPOTLIGHT env var.
+  // The env var is injected by the Next.js build config:
+  // - Webpack: valueInjectionLoader sets globalThis.NEXT_PUBLIC_SENTRY_SPOTLIGHT
   // - Turbopack: valueInjectionLoader sets globalThis.NEXT_PUBLIC_SENTRY_SPOTLIGHT
-  // The browser SDK's getEnvValue() checks both sources.
+  // We handle this in the Next.js SDK rather than the browser SDK because the browser SDK's
+  // auto-detection is development-only (stripped from production builds that users install).
+  const spotlightEnvValue = globalWithInjectedValues.NEXT_PUBLIC_SENTRY_SPOTLIGHT;
+  if (spotlightEnvValue !== undefined) {
+    // Parse the env var value (could be 'true', 'false', or a URL)
+    const boolValue = envToBool(spotlightEnvValue, { strict: true });
+    const envSpotlight = boolValue !== null ? boolValue : spotlightEnvValue;
+    const spotlightValue = resolveSpotlightOptions(options.spotlight, envSpotlight);
+
+    if (spotlightValue) {
+      const args = typeof spotlightValue === 'string' ? { sidecarUrl: spotlightValue } : undefined;
+      customDefaultIntegrations.push(spotlightBrowserIntegration(args));
+    }
+  }
 
   return customDefaultIntegrations;
 }