feat(spotlight): Add SENTRY_SPOTLIGHT environment variable support for browser SDKs

Enable Spotlight via SENTRY_SPOTLIGHT environment variable across browser frameworks with zero configuration for users.

## Changes

### Core Utilities (@sentry/core)
- Move envToBool from node-core to @sentry/core for reuse
- Add parseSpotlightEnvValue() and resolveSpotlightValue() implementing Spotlight spec precedence rules
- Add unit tests for spotlight utilities

### Framework SDKs with Build-Time Injection
- **Next.js**: webpack DefinePlugin + turbopack valueInjectionLoader
- **Nuxt**: vite:extendConfig hook
- **Astro**: updateConfig with vite define
- **SvelteKit**: New makeSpotlightDefinePlugin() in sentrySvelteKit()

### Framework-Agnostic SDKs (React, Vue, Svelte, Solid)
- Add __VITE_SPOTLIGHT_ENV__ placeholder replaced by Rollup
- ESM: import.meta.env?.VITE_SENTRY_SPOTLIGHT (zero-config for Vite)
- CJS: undefined (requires bundler config)

### Rollup Utils
- Add makeViteSpotlightEnvReplacePlugin() for format-specific replacement

Zero-config experience with 'spotlight run' for Next.js, Nuxt, Astro, SvelteKit, and Vite ESM users.

Author: BYK

dev-packages/rollup-utils/npmHelpers.mjs

@@ -19,6 +19,7 @@ import {
   makeProductionReplacePlugin,
   makeRrwebBuildPlugin,
   makeSucrasePlugin,
+  makeViteSpotlightEnvReplacePlugin,
 } from './plugins/index.mjs';
 import { makePackageNodeEsm } from './plugins/make-esm-plugin.mjs';
 import { mergePlugins } from './utils.mjs';
@@ -121,13 +122,19 @@ export function makeNPMConfigVariants(baseConfig, options = {}) {
 
   if (emitCjs) {
     if (splitDevProd) {
-      variantSpecificConfigs.push({ output: { format: 'cjs', dir: path.join(baseConfig.output.dir, 'cjs/dev') } });
+      variantSpecificConfigs.push({
+        output: { format: 'cjs', dir: path.join(baseConfig.output.dir, 'cjs/dev') },
+        plugins: [makeViteSpotlightEnvReplacePlugin('cjs')],
+      });
       variantSpecificConfigs.push({
         output: { format: 'cjs', dir: path.join(baseConfig.output.dir, 'cjs/prod') },
-        plugins: [makeProductionReplacePlugin()],
+        plugins: [makeProductionReplacePlugin(), makeViteSpotlightEnvReplacePlugin('cjs')],
       });
     } else {
-      variantSpecificConfigs.push({ output: { format: 'cjs', dir: path.join(baseConfig.output.dir, 'cjs') } });
+      variantSpecificConfigs.push({
+        output: { format: 'cjs', dir: path.join(baseConfig.output.dir, 'cjs') },
+        plugins: [makeViteSpotlightEnvReplacePlugin('cjs')],
+      });
     }
   }
 
@@ -139,13 +146,15 @@ export function makeNPMConfigVariants(baseConfig, options = {}) {
           dir: path.join(baseConfig.output.dir, 'esm/dev'),
           plugins: [makePackageNodeEsm()],
         },
+        plugins: [makeViteSpotlightEnvReplacePlugin('esm')],
       });
       variantSpecificConfigs.push({
         output: {
           format: 'esm',
           dir: path.join(baseConfig.output.dir, 'esm/prod'),
           plugins: [makeProductionReplacePlugin(), makePackageNodeEsm()],
         },
+        plugins: [makeViteSpotlightEnvReplacePlugin('esm')],
       });
     } else {
       variantSpecificConfigs.push({
@@ -154,6 +163,7 @@ export function makeNPMConfigVariants(baseConfig, options = {}) {
           dir: path.join(baseConfig.output.dir, 'esm'),
           plugins: [makePackageNodeEsm()],
         },
+        plugins: [makeViteSpotlightEnvReplacePlugin('esm')],
       });
     }
   }

dev-packages/rollup-utils/plugins/npmPlugins.mjs

@@ -168,6 +168,24 @@ export function makeRrwebBuildPlugin({ excludeShadowDom, excludeIframe } = {}) {
   });
 }
 
+/**
+ * Creates a plugin to replace __VITE_SPOTLIGHT_ENV__ with the appropriate value based on output format.
+ * - ESM: import.meta.env?.VITE_SENTRY_SPOTLIGHT (allows Vite to provide zero-config Spotlight support)
+ * - CJS: undefined (import.meta is not available in CJS)
+ *
+ * @param format The output format ('esm' or 'cjs')
+ * @returns A `@rollup/plugin-replace` instance.
+ */
+export function makeViteSpotlightEnvReplacePlugin(format) {
+  const value = format === 'esm' ? 'import.meta.env?.VITE_SENTRY_SPOTLIGHT' : 'undefined';
+  return replace({
+    preventAssignment: true,
+    values: {
+      __VITE_SPOTLIGHT_ENV__: value,
+    },
+  });
+}
+
 /**
  * Plugin that uploads bundle analysis to codecov.
  *

packages/astro/src/client/sdk.ts

@@ -1,9 +1,26 @@
 import type { BrowserOptions } from '@sentry/browser';
 import { getDefaultIntegrations as getBrowserDefaultIntegrations, init as initBrowserSdk } from '@sentry/browser';
 import type { Client, Integration } from '@sentry/core';
-import { applySdkMetadata } from '@sentry/core';
+import { applySdkMetadata, parseSpotlightEnvValue, resolveSpotlightValue } from '@sentry/core';
 import { browserTracingIntegration } from './browserTracingIntegration';
 
+// Type for spotlight-related env vars injected by Vite
+interface SpotlightEnv {
+  PUBLIC_SENTRY_SPOTLIGHT?: string;
+  SENTRY_SPOTLIGHT?: string;
+}
+
+// Access import.meta.env in a way that works with TypeScript
+// Vite replaces this at build time
+function getSpotlightEnv(): SpotlightEnv {
+  try {
+    // @ts-expect-error - import.meta.env is injected by Vite
+    return typeof import.meta !== 'undefined' && import.meta.env ? (import.meta.env as SpotlightEnv) : {};
+  } catch {
+    return {};
+  }
+}
+
 // Tree-shakable guard to remove all code related to tracing
 declare const __SENTRY_TRACING__: boolean;
 
@@ -13,9 +30,16 @@ declare const __SENTRY_TRACING__: boolean;
  * @param options Configuration options for the SDK.
  */
 export function init(options: BrowserOptions): Client | undefined {
+  // Read PUBLIC_SENTRY_SPOTLIGHT (set by spotlight run, Astro uses PUBLIC_ prefix)
+  // OR fallback to SENTRY_SPOTLIGHT (injected by our integration)
+  const spotlightEnv = getSpotlightEnv();
+  const spotlightEnvRaw = spotlightEnv.PUBLIC_SENTRY_SPOTLIGHT || spotlightEnv.SENTRY_SPOTLIGHT;
+  const spotlightEnvValue = parseSpotlightEnvValue(spotlightEnvRaw);
+
   const opts = {
     defaultIntegrations: getDefaultIntegrations(options),
     ...options,
+    spotlight: resolveSpotlightValue(options.spotlight, spotlightEnvValue),
   };
 
   applySdkMetadata(opts, 'astro', ['astro', 'browser']);

packages/astro/src/integration/index.ts

@@ -179,6 +179,15 @@ export const sentryAstro = (options: SentryOptions = {}): AstroIntegration => {
           }
         }
 
+        // Inject SENTRY_SPOTLIGHT env var for client bundles (fallback for manual setup without PUBLIC_ prefix)
+        updateConfig({
+          vite: {
+            define: {
+              'import.meta.env.SENTRY_SPOTLIGHT': JSON.stringify(process.env.SENTRY_SPOTLIGHT || ''),
+            },
+          },
+        });
+
         const isSSR = config && (config.output === 'server' || config.output === 'hybrid');
         const shouldAddMiddleware = sdkEnabled.server && autoInstrumentation?.requestHandler !== false;
 

packages/core/src/index.ts

@@ -69,6 +69,14 @@ export { hasSpansEnabled } from './utils/hasSpansEnabled';
 export { isSentryRequestUrl } from './utils/isSentryRequestUrl';
 export { handleCallbackErrors } from './utils/handleCallbackErrors';
 export { parameterize, fmt } from './utils/parameterize';
+export {
+  envToBool,
+  FALSY_ENV_VALUES,
+  TRUTHY_ENV_VALUES,
+} from './utils/envToBool';
+export type { BoolCastOptions, StrictBoolCast, LooseBoolCast } from './utils/envToBool';
+export { parseSpotlightEnvValue, resolveSpotlightValue } from './utils/spotlight';
+export type { SpotlightConnectionOptions } from './utils/spotlight';
 
 export { addAutoIpAddressToSession } from './utils/ipAddress';
 // eslint-disable-next-line deprecation/deprecation

packages/core/src/utils/envToBool.ts

@@ -0,0 +1,38 @@
+export const FALSY_ENV_VALUES = new Set(['false', 'f', 'n', 'no', 'off', '0']);
+export const TRUTHY_ENV_VALUES = new Set(['true', 't', 'y', 'yes', 'on', '1']);
+
+export type StrictBoolCast = {
+  strict: true;
+};
+
+export type LooseBoolCast = {
+  strict?: false;
+};
+
+export type BoolCastOptions = StrictBoolCast | LooseBoolCast;
+
+export function envToBool(value: unknown, options?: LooseBoolCast): boolean;
+export function envToBool(value: unknown, options: StrictBoolCast): boolean | null;
+export function envToBool(value: unknown, options?: BoolCastOptions): boolean | null;
+/**
+ * A helper function which casts an ENV variable value to `true` or `false` using the constants defined above.
+ * In strict mode, it may return `null` if the value doesn't match any of the predefined values.
+ *
+ * @param value The value of the env variable
+ * @param options -- Only has `strict` key for now, which requires a strict match for `true` in TRUTHY_ENV_VALUES
+ * @returns true/false if the lowercase value matches the predefined values above. If not, null in strict mode,
+ *          and Boolean(value) in loose mode.
+ */
+export function envToBool(value: unknown, options?: BoolCastOptions): boolean | null {
+  const normalized = String(value).toLowerCase();
+
+  if (FALSY_ENV_VALUES.has(normalized)) {
+    return false;
+  }
+
+  if (TRUTHY_ENV_VALUES.has(normalized)) {
+    return true;
+  }
+
+  return options?.strict ? null : Boolean(value);
+}

packages/core/src/utils/spotlight.ts

@@ -0,0 +1,82 @@
+import { debug } from './debug-logger';
+import { envToBool } from './envToBool';
+
+/**
+ * Spotlight configuration option type.
+ * - `undefined` - not configured
+ * - `false` - explicitly disabled
+ * - `true` - enabled with default URL (http://localhost:8969/stream)
+ * - `string` - enabled with custom URL
+ */
+export type SpotlightConnectionOptions = boolean | string | undefined;
+
+/**
+ * Parses a SENTRY_SPOTLIGHT environment variable value.
+ *
+ * Per the Spotlight spec:
+ * - Truthy values ("true", "t", "y", "yes", "on", "1") -> true
+ * - Falsy values ("false", "f", "n", "no", "off", "0") -> false
+ * - Any other non-empty string -> treated as URL
+ * - Empty string or undefined -> undefined
+ *
+ * @see https://develop.sentry.dev/sdk/expected-features/spotlight.md
+ */
+export function parseSpotlightEnvValue(envValue: string | undefined): SpotlightConnectionOptions {
+  if (envValue === undefined || envValue === '') {
+    return undefined;
+  }
+
+  // Try strict boolean parsing first
+  const boolValue = envToBool(envValue, { strict: true });
+  if (boolValue !== null) {
+    return boolValue;
+  }
+
+  // Not a boolean - treat as URL
+  return envValue;
+}
+
+/**
+ * Resolves the final Spotlight configuration value based on the config option and environment variable.
+ *
+ * Precedence rules (per spec):
+ * 1. Config `false` -> DISABLED (ignore env var, log warning)
+ * 2. Config URL string -> USE CONFIG URL (log warning if env var also set to URL)
+ * 3. Config `true` + Env URL -> USE ENV VAR URL (this is the key case!)
+ * 4. Config `true` + Env bool/undefined -> USE DEFAULT URL (true)
+ * 5. Config `undefined` -> USE ENV VAR VALUE
+ *
+ * @see https://develop.sentry.dev/sdk/expected-features/spotlight.md
+ */
+export function resolveSpotlightValue(
+  optionValue: SpotlightConnectionOptions,
+  envValue: SpotlightConnectionOptions,
+): SpotlightConnectionOptions {
+  // Case 1: Config explicitly disables Spotlight
+  if (optionValue === false) {
+    if (envValue !== undefined) {
+      // Per spec: MUST warn when config false ignores env var
+      debug.warn('Spotlight disabled via config, ignoring SENTRY_SPOTLIGHT environment variable');
+    }
+    return false;
+  }
+
+  // Case 2: Config provides explicit URL
+  if (typeof optionValue === 'string') {
+    if (typeof envValue === 'string') {
+      // Per spec: MUST warn when config URL overrides env var URL
+      debug.warn('Spotlight config URL takes precedence over SENTRY_SPOTLIGHT environment variable');
+    }
+    return optionValue;
+  }
+
+  // Case 3 & 4: Config is true - enable Spotlight
+  if (optionValue === true) {
+    // Per spec: If config true AND env var is URL, MUST use env var URL
+    // This enables `spotlight: true` in code while `spotlight run` provides the URL
+    return typeof envValue === 'string' ? envValue : true;
+  }
+
+  // Case 5: Config undefined - fully defer to env var
+  return envValue;
+}

packages/core/test/lib/utils/envToBool.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+import { envToBool, FALSY_ENV_VALUES, TRUTHY_ENV_VALUES } from '../../../src/utils/envToBool';
+
+describe('envToBool', () => {
+  describe('TRUTHY_ENV_VALUES', () => {
+    it.each([...TRUTHY_ENV_VALUES])('returns true for "%s"', value => {
+      expect(envToBool(value)).toBe(true);
+      expect(envToBool(value, { strict: true })).toBe(true);
+    });
+
+    it('handles case insensitivity', () => {
+      expect(envToBool('TRUE')).toBe(true);
+      expect(envToBool('True')).toBe(true);
+      expect(envToBool('YES')).toBe(true);
+      expect(envToBool('Yes')).toBe(true);
+    });
+  });
+
+  describe('FALSY_ENV_VALUES', () => {
+    it.each([...FALSY_ENV_VALUES])('returns false for "%s"', value => {
+      expect(envToBool(value)).toBe(false);
+      expect(envToBool(value, { strict: true })).toBe(false);
+    });
+
+    it('handles case insensitivity', () => {
+      expect(envToBool('FALSE')).toBe(false);
+      expect(envToBool('False')).toBe(false);
+      expect(envToBool('NO')).toBe(false);
+      expect(envToBool('No')).toBe(false);
+    });
+  });
+
+  describe('non-matching values', () => {
+    it('returns null in strict mode for non-matching values', () => {
+      expect(envToBool('http://localhost:8969', { strict: true })).toBe(null);
+      expect(envToBool('random', { strict: true })).toBe(null);
+      expect(envToBool('', { strict: true })).toBe(null);
+    });
+
+    it('returns Boolean(value) in loose mode for non-matching values', () => {
+      expect(envToBool('http://localhost:8969')).toBe(true); // truthy string
+      expect(envToBool('random')).toBe(true); // truthy string
+      expect(envToBool('')).toBe(false); // falsy empty string
+    });
+
+    it('defaults to loose mode when options not provided', () => {
+      expect(envToBool('http://localhost:8969')).toBe(true);
+    });
+  });
+});