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

.github/workflows/build.yml

@@ -927,6 +927,9 @@ jobs:
       NEXT_PUBLIC_E2E_TEST_DSN: 'https://username@domain/123'
       PUBLIC_E2E_TEST_DSN: 'https://username@domain/123'
       REACT_APP_E2E_TEST_DSN: 'https://username@domain/123'
+      VITE_E2E_TEST_DSN: 'https://username@domain/123'
+      # For Spotlight environment variable tests
+      VITE_SENTRY_SPOTLIGHT: 'true'
       E2E_TEST_SENTRY_ORG_SLUG: 'sentry-javascript-sdks'
       E2E_TEST_SENTRY_PROJECT: 'sentry-javascript-e2e-tests'
     strategy:
@@ -1056,6 +1059,9 @@ jobs:
       NEXT_PUBLIC_E2E_TEST_DSN: ${{ secrets.E2E_TEST_DSN }}
       PUBLIC_E2E_TEST_DSN: ${{ secrets.E2E_TEST_DSN }}
       REACT_APP_E2E_TEST_DSN: ${{ secrets.E2E_TEST_DSN }}
+      VITE_E2E_TEST_DSN: ${{ secrets.E2E_TEST_DSN }}
+      # For Spotlight environment variable tests
+      VITE_SENTRY_SPOTLIGHT: 'true'
       E2E_TEST_SENTRY_ORG_SLUG: 'sentry-javascript-sdks'
       E2E_TEST_SENTRY_PROJECT: 'sentry-javascript-e2e-tests'
     strategy:

CHANGELOG.md

@@ -2,7 +2,8 @@
 
 ## Unreleased
 
-- "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
+- feat(browser): Add environment variable support for Spotlight configuration ([#18198](https://github.com/getsentry/sentry-javascript/pull/18198))
+  - `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`
 
 ## 10.29.0
 

dev-packages/e2e-tests/run.ts

@@ -74,6 +74,8 @@ async function run(): Promise<void> {
     NEXT_PUBLIC_E2E_TEST_DSN: dsn,
     PUBLIC_E2E_TEST_DSN: dsn,
     REACT_APP_E2E_TEST_DSN: dsn,
+    VITE_E2E_TEST_DSN: dsn,
+    VITE_SENTRY_SPOTLIGHT: 'true',
     E2E_TEST_SENTRY_ORG_SLUG: process.env.E2E_TEST_SENTRY_ORG_SLUG || DEFAULT_SENTRY_ORG_SLUG,
     E2E_TEST_SENTRY_PROJECT: process.env.E2E_TEST_SENTRY_PROJECT || DEFAULT_SENTRY_PROJECT,
   };

dev-packages/e2e-tests/test-applications/SPOTLIGHT_ENV_TESTS.md

@@ -0,0 +1,199 @@
+# Spotlight Environment Variable E2E Tests
+
+This document describes the E2E tests for Spotlight environment variable handling across different bundlers and module formats.
+
+## Overview
+
+The Sentry JavaScript SDK supports Spotlight configuration via environment variables. The implementation must handle:
+
+1. **Multiple environment variable prefixes** for different frameworks (e.g., `NEXT_PUBLIC_*`, `VITE_*`)
+2. **Different module formats** (ESM vs CJS)
+3. **Different environment variable access methods** (`process.env` vs `import.meta.env`)
+4. **Empty string filtering** (empty strings should be treated as undefined)
+
+## Test Coverage
+
+### Next.js Tests (`nextjs-15/tests/spotlight-env.test.ts`)
+
+Tests the **CJS build** scenario where `import.meta` must be stripped to avoid syntax errors.
+
+**Test Page**: `/spotlight-env-test`
+**Source**: `nextjs-15/app/spotlight-env-test/page.tsx`
+
+#### Tests:
+
+1. **`respects NEXT_PUBLIC_SENTRY_SPOTLIGHT environment variable`**
+   - Verifies that `NEXT_PUBLIC_SENTRY_SPOTLIGHT=true` enables Spotlight
+   - Checks that the Spotlight integration is registered
+
+2. **`NEXT_PUBLIC_SENTRY_SPOTLIGHT takes precedence over SENTRY_SPOTLIGHT`**
+   - Verifies that `SENTRY_SPOTLIGHT` (backend-only) is not accessible in browser
+   - Ensures framework-specific vars have priority
+
+3. **`handles empty string environment variables correctly`**
+   - Documents expected behavior: empty strings should disable Spotlight
+   - Tests that `resolveSpotlightOptions` filters empty strings
+
+4. **`process.env check works without errors in CJS build`**
+   - **Critical test**: Verifies no `import.meta` syntax errors in CJS build
+   - Checks that the rollup plugin successfully stripped ESM-only code
+   - Monitors console for syntax errors
+
+#### Environment Setup:
+
+```bash
+NEXT_PUBLIC_SENTRY_SPOTLIGHT=true
+# SENTRY_SPOTLIGHT can be set for backend, but won't be exposed to browser
+```
+
+### Vite Tests (`browser-webworker-vite/tests/spotlight-env.test.ts`)
+
+Tests the **ESM build** scenario where `import.meta` should be present and functional.
+
+**Test Page**: `/spotlight-env-test.html`
+**Source**: `browser-webworker-vite/src/spotlight-env-test.ts`
+
+#### Tests:
+
+1. **`respects VITE_SENTRY_SPOTLIGHT environment variable`**
+   - Verifies that `VITE_SENTRY_SPOTLIGHT=true` enables Spotlight
+   - Checks that the Spotlight integration is registered
+
+2. **`import.meta.env is available in ESM build`**
+   - **Critical test**: Verifies `import.meta` is present in ESM builds
+   - Checks that `import.meta.env.VITE_SENTRY_SPOTLIGHT` is accessible
+   - Confirms the build format is ESM
+
+3. **`process.env also works via Vite transformation`**
+   - Verifies that Vite transforms `process.env` references
+   - Both `process.env` and `import.meta.env` should work
+
+4. **`handles empty string environment variables correctly`**
+   - Documents expected behavior for empty strings
+   - Tests that `resolveSpotlightOptions` filters empty strings
+
+5. **`no syntax errors from import.meta in ESM build`**
+   - Verifies no syntax errors when using `import.meta`
+   - Monitors console for errors
+
+6. **`getEnvValue function works with import.meta.env`**
+   - Tests the `getEnvValue` utility function
+   - Verifies it successfully reads from `import.meta.env`
+
+#### Environment Setup:
+
+```bash
+VITE_SENTRY_SPOTLIGHT=true
+```
+
+## Implementation Details
+
+### Rollup Plugins
+
+Two rollup plugins handle module-format-specific code:
+
+1. **`makeStripEsmPlugin()`** - Strips ESM-only code from CJS builds
+   - Removes code between `/* rollup-esm-only */` and `/* rollup-esm-only-end */`
+   - Applied to all CJS builds
+
+2. **`makeStripCjsPlugin()`** - Strips CJS-only code from ESM builds
+   - Removes code between `/* rollup-cjs-only */` and `/* rollup-cjs-only-end */`
+   - Applied to all ESM builds
+
+### Source Code
+
+**File**: `packages/browser/src/utils/env.ts`
+
+The `import.meta.env` check is wrapped in special comments:
+
+```typescript
+/* rollup-esm-only */
+// Check import.meta.env (Vite, Astro, SvelteKit, etc.)
+try {
+  if (typeof import.meta !== 'undefined' && import.meta.env) {
+    const value = import.meta.env[key];
+    if (value !== undefined) {
+      return value;
+    }
+  }
+} catch (e) {
+  // Silently ignore
+}
+/* rollup-esm-only-end */
+```
+
+This code is:
+
+- **Included** in ESM builds (Vite, Astro, SvelteKit)
+- **Stripped** from CJS builds (Next.js, Webpack, etc.)
+
+### Empty String Handling
+
+**File**: `packages/core/src/utils/resolveSpotlightOptions.ts`
+
+The shared `resolveSpotlightOptions` function filters empty/whitespace strings:
+
+```typescript
+// Treat empty/whitespace-only strings as undefined
+const envUrl = typeof envSpotlight === 'string' && envSpotlight.trim() !== '' ? envSpotlight : undefined;
+```
+
+This ensures:
+
+- Empty strings never enable Spotlight
+- Whitespace-only strings are treated as undefined
+- No invalid URL connections are attempted
+
+## Running the Tests
+
+### Next.js Tests
+
+```bash
+cd dev-packages/e2e-tests/test-applications/nextjs-15
+NEXT_PUBLIC_SENTRY_SPOTLIGHT=true pnpm test tests/spotlight-env.test.ts
+```
+
+### Vite Tests
+
+```bash
+cd dev-packages/e2e-tests/test-applications/browser-webworker-vite
+VITE_SENTRY_SPOTLIGHT=true pnpm test tests/spotlight-env.test.ts
+```
+
+## Expected Outcomes
+
+### Next.js (CJS)
+
+- ✅ `process.env.NEXT_PUBLIC_SENTRY_SPOTLIGHT` accessible
+- ✅ `SENTRY_SPOTLIGHT` NOT accessible (backend-only)
+- ✅ No `import.meta` syntax in output
+- ✅ No syntax errors
+- ✅ Spotlight integration enabled
+
+### Vite (ESM)
+
+- ✅ `import.meta.env.VITE_SENTRY_SPOTLIGHT` accessible
+- ✅ `process.env.VITE_SENTRY_SPOTLIGHT` NOT accessible (Vite only exposes import.meta.env)
+- ✅ `import.meta` syntax present in output
+- ✅ No syntax errors
+- ✅ Spotlight integration enabled
+
+## Troubleshooting
+
+### Syntax Error: Cannot use import.meta outside a module
+
+- **Cause**: `import.meta` code not stripped from CJS build
+- **Fix**: Verify `makeStripEsmPlugin()` is applied to CJS builds
+- **Check**: Look for `/* rollup-esm-only */` comments in source
+
+### Spotlight not enabled despite env var set
+
+- **Cause**: Empty string or wrong prefix
+- **Fix**: Use correct prefix (`NEXT_PUBLIC_*` for Next.js, `VITE_*` for Vite)
+- **Check**: Verify `resolveSpotlightOptions` receives non-empty string
+
+### import.meta.env returns undefined in Vite
+
+- **Cause**: `import.meta` code stripped from ESM build
+- **Fix**: Verify `makeStripEsmPlugin()` is NOT applied to ESM builds
+- **Check**: ESM builds should only use `makeStripCjsPlugin()`

dev-packages/e2e-tests/test-applications/angular-17/src/index.html

@@ -1,13 +1,13 @@
 <!doctype html>
 <html lang="en">
-<head>
-  <meta charset="utf-8">
-  <title>Angular17</title>
-  <base href="/">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <link rel="icon" type="image/x-icon" href="favicon.ico">
-</head>
-<body>
-  <app-root></app-root>
-</body>
+  <head>
+    <meta charset="utf-8" />
+    <title>Angular17</title>
+    <base href="/" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="icon" type="image/x-icon" href="favicon.ico" />
+  </head>
+  <body>
+    <app-root></app-root>
+  </body>
 </html>

dev-packages/e2e-tests/test-applications/angular-18/src/index.html

@@ -1,13 +1,13 @@
 <!doctype html>
 <html lang="en">
-<head>
-  <meta charset="utf-8">
-  <title>Angular 18</title>
-  <base href="/">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <link rel="icon" type="image/x-icon" href="favicon.ico">
-</head>
-<body>
-  <app-root></app-root>
-</body>
+  <head>
+    <meta charset="utf-8" />
+    <title>Angular 18</title>
+    <base href="/" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="icon" type="image/x-icon" href="favicon.ico" />
+  </head>
+  <body>
+    <app-root></app-root>
+  </body>
 </html>

dev-packages/e2e-tests/test-applications/angular-19/src/index.html

@@ -1,13 +1,13 @@
 <!doctype html>
 <html lang="en">
-<head>
-  <meta charset="utf-8">
-  <title>Angular19</title>
-  <base href="/">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <link rel="icon" type="image/x-icon" href="favicon.ico">
-</head>
-<body>
-  <app-root></app-root>
-</body>
+  <head>
+    <meta charset="utf-8" />
+    <title>Angular19</title>
+    <base href="/" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="icon" type="image/x-icon" href="favicon.ico" />
+  </head>
+  <body>
+    <app-root></app-root>
+  </body>
 </html>

dev-packages/e2e-tests/test-applications/browser-webworker-vite/package.json

@@ -4,11 +4,11 @@
   "version": "0.0.0",
   "type": "module",
   "scripts": {
-    "dev": "vite",
+    "dev": "vite --port 3030",
     "build": "rm -rf dist && tsc && vite build",
     "preview": "vite preview --port 3030",
     "test": "playwright test",
-    "test:build": "pnpm install && pnpm build",
+    "test:build": "pnpm install",
     "test:assert": "pnpm test"
   },
   "devDependencies": {

dev-packages/e2e-tests/test-applications/browser-webworker-vite/playwright.config.mjs

@@ -1,7 +1,8 @@
 import { getPlaywrightConfig } from '@sentry-internal/test-utils';
 
 const config = getPlaywrightConfig({
-  startCommand: `pnpm preview`,
+  // Use vite dev server to test development-mode behavior (e.g., Spotlight auto-enablement)
+  startCommand: `pnpm dev`,
   eventProxyFile: 'start-event-proxy.mjs',
   eventProxyPort: 3031,
   port: 3030,

dev-packages/e2e-tests/test-applications/browser-webworker-vite/spotlight-env-test.html

@@ -0,0 +1,38 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Spotlight Env Test - Vite</title>
+  </head>
+  <body>
+    <h1>Spotlight Environment Variable Test (Vite)</h1>
+
+    <div id="env-vars" data-testid="env-vars">
+      <h2>Environment Variables</h2>
+      <div data-testid="vite-spotlight">VITE_SENTRY_SPOTLIGHT: <span id="vite-spotlight-value">Loading...</span></div>
+      <div data-testid="process-env-spotlight">
+        process.env.SENTRY_SPOTLIGHT: <span id="process-env-value">Loading...</span>
+      </div>
+      <div data-testid="import-meta-env-spotlight">
+        import.meta.env.VITE_SENTRY_SPOTLIGHT: <span id="import-meta-value">Loading...</span>
+      </div>
+    </div>
+
+    <div id="spotlight-status" data-testid="spotlight-status">
+      <h2>Spotlight Integration Status</h2>
+      <div data-testid="spotlight-integration-found">
+        Spotlight Integration: <span id="spotlight-status-value">Loading...</span>
+      </div>
+    </div>
+
+    <div id="build-format" data-testid="build-format">
+      <h2>Build Format Check</h2>
+      <div data-testid="import-meta-available">
+        import.meta available: <span id="import-meta-available-value">Loading...</span>
+      </div>
+    </div>
+
+    <script type="module" src="/src/spotlight-env-test.ts"></script>
+  </body>
+</html>

dev-packages/e2e-tests/test-applications/browser-webworker-vite/src/main.ts

@@ -3,7 +3,7 @@ import MyWorker2 from './worker2.ts?worker';
 import * as Sentry from '@sentry/browser';
 
 Sentry.init({
-  dsn: import.meta.env.PUBLIC_E2E_TEST_DSN,
+  dsn: import.meta.env.VITE_E2E_TEST_DSN,
   environment: import.meta.env.MODE || 'development',
   tracesSampleRate: 1.0,
   debug: true,