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:
@@ -1060,6 +1063,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:

.size-limit.js

@@ -213,7 +213,7 @@ module.exports = [
     import: createImport('init'),
     ignore: ['next/router', 'next/constants'],
     gzip: true,
-    limit: '46 KB',
+    limit: '47 KB',
   },
   // SvelteKit SDK (ESM)
   {

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`
 
 Work in this release was contributed by @sebws. Thank you for your contribution!
 

CONTRIBUTING.md

@@ -73,6 +73,72 @@ the tests in each location. Check out the `scripts` entry of the corresponding `
 
 Note: you must run `yarn build` before `yarn test` will work.
 
+## Running E2E Tests Locally
+
+The E2E tests in `dev-packages/e2e-tests/test-applications/` use Playwright and pnpm. To run them locally:
+
+### Prerequisites
+
+1. **Enable pnpm support in Volta** (required for E2E tests):
+
+   ```bash
+   export VOLTA_FEATURE_PNPM=1
+   ```
+
+   Add this to your shell profile (`.bashrc`, `.zshrc`, etc.) for persistence.
+
+2. **Build the SDK packages** you want to test:
+
+   ```bash
+   yarn build:dev:filter @sentry/nextjs  # or whichever package you're testing
+   ```
+
+### Running a specific E2E test app
+
+1. Navigate to the test application directory:
+
+   ```bash
+   cd dev-packages/e2e-tests/test-applications/<app-name>
+   ```
+
+2. Install dependencies:
+
+   ```bash
+   pnpm install
+   ```
+
+3. Link local SDK packages (to test your changes instead of the published version):
+
+   ```bash
+   # Remove existing @sentry packages and create symlinks to local builds
+   rm -rf node_modules/@sentry
+   mkdir -p node_modules/@sentry
+   ln -sf ../../../../../../../../packages/nextjs node_modules/@sentry/nextjs
+   ln -sf ../../../../../../../../packages/core node_modules/@sentry/core
+   ln -sf ../../../../../../../../packages/browser node_modules/@sentry/browser
+   ln -sf ../../../../../../../../packages/react node_modules/@sentry/react
+   # Add other packages as needed for your test
+   ```
+
+4. Install Playwright browsers (first time only):
+
+   ```bash
+   npx playwright install chromium
+   ```
+
+5. Run the tests:
+
+   ```bash
+   npx playwright test
+   ```
+
+### Troubleshooting
+
+- **WSL2 Chromium issues**: If you encounter "Invalid file descriptor to ICU data" or segfaults, you may need a newer
+  Playwright version. The test apps use `@playwright/test: ~1.56.0` which works in WSL2.
+- **Stale builds**: After making SDK changes, rebuild with `yarn build:dev:filter @sentry/<package>` and re-link.
+- **Port conflicts**: Check if the test app's port (usually 3030) is available.
+
 ## Debug Build Flags
 
 Throughout the codebase, you will find a `__DEBUG_BUILD__` constant. This flag serves two purposes:

dev-packages/e2e-tests/.gitignore

@@ -4,3 +4,4 @@ tmp
 .tmp_build_stderr
 pnpm-lock.yaml
 .last-run.json
+.next

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,
     // Pass workspace root so tests copied to temp dirs can find local packages

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>