feat(browser): Enable Spotlight via SENTRY_SPOTLIGHT env var

- Move envToBool utility from node-core to core for code sharing
- Add spotlight option to BrowserSpecificOptions type
- Support SENTRY_SPOTLIGHT env var in browser SDK with graceful fallback
- Auto-inject spotlightBrowserIntegration when enabled via env var
- Match Node.js behavior: truthy values use default URL, custom strings use that URL

Author: BYK

packages/browser/src/client.ts

@@ -63,6 +63,18 @@ type BrowserSpecificOptions = BrowserClientReplayOptions &
      * @default false
      */
     propagateTraceparent?: boolean;
+
+    /**
+     * If you use Spotlight by Sentry during development, use
+     * this option to forward captured Sentry events to Spotlight.
+     *
+     * Either set it to true, or provide a specific Spotlight Sidecar URL.
+     *
+     * More details: https://spotlightjs.com/
+     *
+     * IMPORTANT: Only set this option to `true` while developing, not in production!
+     */
+    spotlight?: boolean | string;
   };
 /**
  * Configuration options for the Sentry Browser SDK.

packages/browser/src/sdk.ts

@@ -1,6 +1,7 @@
 import type { Client, Integration, Options } from '@sentry/core';
 import {
   dedupeIntegration,
+  envToBool,
   functionToStringIntegration,
   getIntegrationsToSetup,
   inboundFiltersIntegration,
@@ -15,6 +16,7 @@ import { browserSessionIntegration } from './integrations/browsersession';
 import { globalHandlersIntegration } from './integrations/globalhandlers';
 import { httpContextIntegration } from './integrations/httpcontext';
 import { linkedErrorsIntegration } from './integrations/linkederrors';
+import { INTEGRATION_NAME as SPOTLIGHT_INTEGRATION_NAME, spotlightBrowserIntegration } from './integrations/spotlight';
 import { defaultStackParser } from './stack-parsers';
 import { makeFetchTransport } from './transports/fetch';
 import { checkAndWarnIfIsEmbeddedBrowserExtension } from './utils/detectBrowserExtension';
@@ -90,6 +92,17 @@ export function init(options: BrowserOptions = {}): Client | undefined {
   const shouldDisableBecauseIsBrowserExtenstion =
     !options.skipBrowserExtensionCheck && checkAndWarnIfIsEmbeddedBrowserExtension();
 
+  // Read spotlight config from env var with graceful fallback
+  // This will be replaced at build time by bundlers like webpack/vite
+  let spotlightFromEnv: boolean | string | undefined;
+  if (typeof process !== 'undefined' && process.env && process.env.SENTRY_SPOTLIGHT !== undefined) {
+    const envValue = process.env.SENTRY_SPOTLIGHT;
+    const parsedEnvValue = envToBool(envValue, { strict: true });
+    spotlightFromEnv = parsedEnvValue ?? envValue;
+  }
+
+  const spotlight = options.spotlight ?? spotlightFromEnv;
+
   const clientOptions: BrowserClientOptions = {
     ...options,
     enabled: shouldDisableBecauseIsBrowserExtenstion ? false : options.enabled,
@@ -100,7 +113,18 @@ export function init(options: BrowserOptions = {}): Client | undefined {
         options.defaultIntegrations == null ? getDefaultIntegrations(options) : options.defaultIntegrations,
     }),
     transport: options.transport || makeFetchTransport,
+    spotlight,
   };
+
+  // Auto-add spotlight integration if enabled and not already present
+  if (spotlight && !clientOptions.integrations.some(({ name }) => name === SPOTLIGHT_INTEGRATION_NAME)) {
+    clientOptions.integrations.push(
+      spotlightBrowserIntegration({
+        sidecarUrl: typeof spotlight === 'string' ? spotlight : undefined,
+      }),
+    );
+  }
+
   return initAndBind(BrowserClient, clientOptions);
 }
 

packages/core/src/index.ts

@@ -313,6 +313,8 @@ export { flushIfServerless } from './utils/flushIfServerless';
 export { SDK_VERSION } from './utils/version';
 export { getDebugImagesForResources, getFilenameToDebugIdMap } from './utils/debug-ids';
 export { escapeStringForRegex } from './vendor/escapeStringForRegex';
+export { envToBool, TRUTHY_ENV_VALUES, FALSY_ENV_VALUES } from './utils/envToBool';
+export type { BoolCastOptions, StrictBoolCast, LooseBoolCast } from './utils/envToBool';
 
 export type { Attachment } from './types-hoist/attachment';
 export type {

packages/node-core/src/utils/envToBool.ts renamed to packages/core/src/utils/envToBool.ts

@@ -43,7 +43,6 @@ export { initializeEsmLoader } from './sdk/esmLoader';
 export { isCjs } from './utils/detection';
 export { ensureIsWrapped } from './utils/ensureIsWrapped';
 export { createMissingInstrumentationContext } from './utils/createMissingInstrumentationContext';
-export { envToBool } from './utils/envToBool';
 export { makeNodeTransport, type NodeTransportOptions } from './transports';
 export type { HTTPModuleRequestIncomingMessage } from './transports/http-module';
 export { NodeClient } from './sdk/client';
@@ -112,6 +111,7 @@ export {
   startSession,
   captureSession,
   endSession,
+  envToBool,
   addIntegration,
   startSpan,
   startSpanManual,

packages/node-core/test/utils/envToBool.test.ts renamed to packages/core/test/utils/envToBool.test.ts

@@ -4,6 +4,7 @@ import {
   consoleIntegration,
   consoleSandbox,
   debug,
+  envToBool,
   functionToStringIntegration,
   getCurrentScope,
   getIntegrationsToSetup,
@@ -37,7 +38,6 @@ import { systemErrorIntegration } from '../integrations/systemError';
 import { makeNodeTransport } from '../transports';
 import type { NodeClientOptions, NodeOptions } from '../types';
 import { isCjs } from '../utils/detection';
-import { envToBool } from '../utils/envToBool';
 import { defaultStackParser, getSentryRelease } from './api';
 import { NodeClient } from './client';
 import { initializeEsmLoader } from './esmLoader';