feat(browser): Add environment variable support for Spotlight configuration

Implements full Spotlight spec with support for multiple framework-specific
environment variable prefixes. Adds defensive environment variable access
for both process.env and import.meta.env to support various bundlers.

Supported environment variables (in priority order):
- SENTRY_SPOTLIGHT (base/official)
- PUBLIC_SENTRY_SPOTLIGHT (SvelteKit, Astro, Qwik)
- NEXT_PUBLIC_SENTRY_SPOTLIGHT (Next.js)
- VITE_SENTRY_SPOTLIGHT (Vite)
- NUXT_PUBLIC_SENTRY_SPOTLIGHT (Nuxt)
- REACT_APP_SENTRY_SPOTLIGHT (Create React App)
- VUE_APP_SENTRY_SPOTLIGHT (Vue CLI)
- GATSBY_SENTRY_SPOTLIGHT (Gatsby)

Refactors envToBool utility from node-core to core package for shared usage.
Adds resolveSpotlightOptions utility to ensure consistent precedence rules
across Browser and Node SDKs.

Includes comprehensive test coverage for all new utilities and integration
tests for environment variable precedence behavior.

Author: BYK

CHANGELOG.md

@@ -2,8 +2,17 @@
 
 ## Unreleased
 
+- feat(browser): Add environment variable support for Spotlight configuration
+  - Supports `SENTRY_SPOTLIGHT`, `PUBLIC_SENTRY_SPOTLIGHT`, `NEXT_PUBLIC_SENTRY_SPOTLIGHT`, `VITE_SENTRY_SPOTLIGHT`, `NUXT_PUBLIC_SENTRY_SPOTLIGHT`, `REACT_APP_SENTRY_SPOTLIGHT`, `VUE_APP_SENTRY_SPOTLIGHT`, and `GATSBY_SENTRY_SPOTLIGHT` with proper precedence
+  - Adds defensive environment variable access for both `process.env` and `import.meta.env`
+- feat(core): Add shared utilities for Spotlight configuration
+  - Moves `envToBool` from `node-core` to `core` for shared usage across SDKs
+  - Adds `resolveSpotlightOptions` utility for consistent precedence rules
+- feat(node): Update Spotlight configuration to use shared utilities
 - fix(node): Fix Spotlight configuration precedence to match specification (#18195)
 
+- "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
+
 ## 10.25.0
 
 - feat(browser): Include Spotlight in development bundles ([#18078](https://github.com/getsentry/sentry-javascript/pull/18078))

packages/aws-serverless/src/init.ts

@@ -2,7 +2,7 @@ import type { Integration, Options } from '@sentry/core';
 import { applySdkMetadata, debug, getSDKSource } from '@sentry/core';
 import type { NodeClient, NodeOptions } from '@sentry/node';
 import { getDefaultIntegrationsWithoutPerformance, initWithoutDefaultIntegrations } from '@sentry/node';
-import { envToBool } from '@sentry/node-core';
+import { envToBool } from '@sentry/core';
 import { DEBUG_BUILD } from './debug-build';
 import { awsIntegration } from './integration/aws';
 import { awsLambdaIntegration } from './integration/awslambda';

packages/browser/src/client.ts

@@ -70,9 +70,26 @@ type BrowserSpecificOptions = BrowserClientReplayOptions &
      *
      * Either set it to true, or provide a specific Spotlight Sidecar URL.
      *
+     * Alternatively, you can configure Spotlight using environment variables:
+     * - SENTRY_SPOTLIGHT (base/official name)
+     * - PUBLIC_SENTRY_SPOTLIGHT (SvelteKit, Astro, Qwik)
+     * - NEXT_PUBLIC_SENTRY_SPOTLIGHT (Next.js)
+     * - VITE_SENTRY_SPOTLIGHT (Vite)
+     * - NUXT_PUBLIC_SENTRY_SPOTLIGHT (Nuxt)
+     * - REACT_APP_SENTRY_SPOTLIGHT (Create React App)
+     * - VUE_APP_SENTRY_SPOTLIGHT (Vue CLI)
+     * - GATSBY_SENTRY_SPOTLIGHT (Gatsby)
+     *
+     * Precedence rules:
+     * - If this option is `false`, Spotlight is disabled (env vars ignored)
+     * - If this option is a string URL, that URL is used (env vars ignored)
+     * - If this option is `true` and env var is a URL, the env var URL is used
+     * - If this option is `undefined`, the env var value is used (if set)
+     *
      * More details: https://spotlightjs.com/
      *
      * IMPORTANT: Only set this option to `true` while developing, not in production!
+     * Spotlight is automatically excluded from production bundles.
      */
     spotlight?: boolean | string;
   };

packages/browser/src/sdk.ts

@@ -5,6 +5,7 @@ import {
   getIntegrationsToSetup,
   inboundFiltersIntegration,
   initAndBind,
+  resolveSpotlightOptions,
   stackParserFromStackParserOptions,
 } from '@sentry/core';
 import type { BrowserClientOptions, BrowserOptions } from './client';
@@ -19,6 +20,7 @@ import { spotlightBrowserIntegration } from './integrations/spotlight';
 import { defaultStackParser } from './stack-parsers';
 import { makeFetchTransport } from './transports/fetch';
 import { checkAndWarnIfIsEmbeddedBrowserExtension } from './utils/detectBrowserExtension';
+import { getSpotlightConfig } from './utils/spotlightConfig';
 
 /** Get the default integrations for the browser SDK. */
 export function getDefaultIntegrations(_options: Options): Integration[] {
@@ -95,11 +97,15 @@ export function init(options: BrowserOptions = {}): Client | undefined {
     options.defaultIntegrations == null ? getDefaultIntegrations(options) : options.defaultIntegrations;
 
   /* rollup-include-development-only */
-  if (options.spotlight) {
+  // Resolve Spotlight configuration with proper precedence
+  const envSpotlight = getSpotlightConfig();
+  const spotlightValue = resolveSpotlightOptions(options.spotlight, envSpotlight);
+
+  if (spotlightValue) {
     if (!defaultIntegrations) {
       defaultIntegrations = [];
     }
-    const args = typeof options.spotlight === 'string' ? { sidecarUrl: options.spotlight } : undefined;
+    const args = typeof spotlightValue === 'string' ? { sidecarUrl: spotlightValue } : undefined;
     defaultIntegrations.push(spotlightBrowserIntegration(args));
   }
   /* rollup-include-development-only-end */

packages/browser/src/utils/env.ts

@@ -0,0 +1,38 @@
+/**
+ * Safely gets an environment variable value with defensive guards for browser environments.
+ * Checks both process.env and import.meta.env with proper error handling.
+ *
+ * @param key - The environment variable key to look up
+ * @returns The value of the environment variable or undefined if not found
+ */
+export function getEnvValue(key: string): string | undefined {
+  // Try process.env first (available in some bundlers like Webpack, Rspack)
+  try {
+    if (typeof process !== 'undefined' && process.env) {
+      const value = process.env[key];
+      if (value !== undefined) {
+        return value;
+      }
+    }
+  } catch (e) {
+    // Silently ignore - process might not be accessible or might throw in some environments
+  }
+
+  // Try import.meta.env (available in Vite, Rollup, and other modern bundlers)
+  try {
+    // @ts-expect-error import.meta.env is not always available in all environments
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    if (typeof import.meta !== 'undefined' && import.meta.env) {
+      // @ts-expect-error import.meta.env is not always available in all environments
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      const value = import.meta.env[key];
+      if (value !== undefined) {
+        return String(value);
+      }
+    }
+  } catch (e) {
+    // Silently ignore - import.meta might not be accessible or might throw in some environments
+  }
+
+  return undefined;
+}

packages/browser/src/utils/spotlightConfig.ts

@@ -0,0 +1,53 @@
+import { debug, envToBool } from '@sentry/core';
+import { DEBUG_BUILD } from '../debug-build';
+import { getEnvValue } from './env';
+
+/**
+ * Environment variable keys to check for Spotlight configuration, in priority order.
+ * The first one found with a value will be used.
+ */
+const SPOTLIGHT_ENV_KEYS = [
+  'SENTRY_SPOTLIGHT', // Base/official name - works in Parcel, Webpack, Rspack, Rollup, Rolldown, Node.js
+  'PUBLIC_SENTRY_SPOTLIGHT', // SvelteKit, Astro, Qwik
+  'NEXT_PUBLIC_SENTRY_SPOTLIGHT', // Next.js
+  'VITE_SENTRY_SPOTLIGHT', // Vite
+  'NUXT_PUBLIC_SENTRY_SPOTLIGHT', // Nuxt
+  'REACT_APP_SENTRY_SPOTLIGHT', // Create React App
+  'VUE_APP_SENTRY_SPOTLIGHT', // Vue CLI
+  'GATSBY_SENTRY_SPOTLIGHT', // Gatsby
+] as const;
+
+/**
+ * Gets the Spotlight configuration from environment variables.
+ * Checks multiple environment variable prefixes in priority order to support
+ * different bundlers and frameworks.
+ *
+ * @returns The resolved Spotlight configuration (boolean | string | undefined)
+ */
+export function getSpotlightConfig(): boolean | string | undefined {
+  for (const key of SPOTLIGHT_ENV_KEYS) {
+    const value = getEnvValue(key);
+
+    if (value !== undefined) {
+      // Try to parse as boolean first (strict mode)
+      const boolValue = envToBool(value, { strict: true });
+
+      if (boolValue !== null) {
+        // It's a valid boolean value
+        if (DEBUG_BUILD) {
+          debug.log(`[Spotlight] Found ${key}=${String(boolValue)} in environment variables`);
+        }
+        return boolValue;
+      }
+
+      // Not a boolean, treat as custom URL string
+      if (DEBUG_BUILD) {
+        debug.log(`[Spotlight] Found ${key}=${value} (custom URL) in environment variables`);
+      }
+      return value;
+    }
+  }
+
+  // No Spotlight configuration found in environment
+  return undefined;
+}

packages/browser/test/sdk.test.ts

@@ -234,6 +234,161 @@ describe('init', () => {
     });
   });
 
+  describe('Spotlight environment variable support', () => {
+    let originalProcess: typeof globalThis.process | undefined;
+
+    afterEach(() => {
+      if (originalProcess !== undefined) {
+        globalThis.process = originalProcess;
+      } else {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        delete (globalThis as any).process;
+      }
+    });
+
+    it('uses environment variable when options.spotlight is undefined', () => {
+      originalProcess = globalThis.process;
+      globalThis.process = {
+        env: {
+          SENTRY_SPOTLIGHT: 'true',
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any;
+
+      // @ts-expect-error this is fine for testing
+      const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+      const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, spotlight: undefined });
+      init(options);
+
+      const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+      // Spotlight integration should be added
+      const spotlightIntegration = optionsPassed?.integrations.find((i: Integration) => i.name === 'SpotlightBrowser');
+      expect(spotlightIntegration).toBeDefined();
+    });
+
+    it('does not add Spotlight when environment variable is false', () => {
+      originalProcess = globalThis.process;
+      globalThis.process = {
+        env: {
+          SENTRY_SPOTLIGHT: 'false',
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any;
+
+      // @ts-expect-error this is fine for testing
+      const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+      const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, spotlight: undefined });
+      init(options);
+
+      const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+      // Spotlight integration should NOT be added
+      const spotlightIntegration = optionsPassed?.integrations.find((i: Integration) => i.name === 'SpotlightBrowser');
+      expect(spotlightIntegration).toBeUndefined();
+    });
+
+    it('options.spotlight=false takes precedence over environment variable', () => {
+      originalProcess = globalThis.process;
+      globalThis.process = {
+        env: {
+          SENTRY_SPOTLIGHT: 'true',
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any;
+
+      // @ts-expect-error this is fine for testing
+      const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+      const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, spotlight: false });
+      init(options);
+
+      const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+      // Spotlight integration should NOT be added even though env var is true
+      const spotlightIntegration = optionsPassed?.integrations.find((i: Integration) => i.name === 'SpotlightBrowser');
+      expect(spotlightIntegration).toBeUndefined();
+    });
+
+    it('options.spotlight=url takes precedence over environment variable', () => {
+      originalProcess = globalThis.process;
+      const customUrl = 'http://custom:1234/stream';
+      globalThis.process = {
+        env: {
+          SENTRY_SPOTLIGHT: 'http://env:5678/stream',
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any;
+
+      // @ts-expect-error this is fine for testing
+      const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+      const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, spotlight: customUrl });
+      init(options);
+
+      const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+      // Spotlight integration should be added (we can't easily check the URL here without deeper inspection)
+      const spotlightIntegration = optionsPassed?.integrations.find((i: Integration) => i.name === 'SpotlightBrowser');
+      expect(spotlightIntegration).toBeDefined();
+    });
+
+    it('uses environment variable URL when options.spotlight=true', () => {
+      originalProcess = globalThis.process;
+      globalThis.process = {
+        env: {
+          SENTRY_SPOTLIGHT: 'http://env:5678/stream',
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any;
+
+      // @ts-expect-error this is fine for testing
+      const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+      const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, spotlight: true });
+      init(options);
+
+      const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+      // Spotlight integration should be added
+      const spotlightIntegration = optionsPassed?.integrations.find((i: Integration) => i.name === 'SpotlightBrowser');
+      expect(spotlightIntegration).toBeDefined();
+    });
+
+    it('respects priority order: SENTRY_SPOTLIGHT over PUBLIC_SENTRY_SPOTLIGHT', () => {
+      originalProcess = globalThis.process;
+      globalThis.process = {
+        env: {
+          SENTRY_SPOTLIGHT: 'true',
+          PUBLIC_SENTRY_SPOTLIGHT: 'false',
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any;
+
+      // @ts-expect-error this is fine for testing
+      const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+      const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, spotlight: undefined });
+      init(options);
+
+      const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+      // Spotlight integration should be added (SENTRY_SPOTLIGHT=true wins)
+      const spotlightIntegration = optionsPassed?.integrations.find((i: Integration) => i.name === 'SpotlightBrowser');
+      expect(spotlightIntegration).toBeDefined();
+    });
+
+    it('uses framework-specific prefix when base is not set', () => {
+      originalProcess = globalThis.process;
+      globalThis.process = {
+        env: {
+          NEXT_PUBLIC_SENTRY_SPOTLIGHT: 'true',
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any;
+
+      // @ts-expect-error this is fine for testing
+      const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
+      const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, spotlight: undefined });
+      init(options);
+
+      const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
+      // Spotlight integration should be added
+      const spotlightIntegration = optionsPassed?.integrations.find((i: Integration) => i.name === 'SpotlightBrowser');
+      expect(spotlightIntegration).toBeDefined();
+    });
+  });
+
   it('returns a client from init', () => {
     const client = init();
     expect(client).not.toBeUndefined();