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

.cursor/plans/migrate_e2e_to_spotlight_358ad839.plan.md

@@ -0,0 +1,147 @@
+---
+name: Migrate E2E to Spotlight
+overview: Replace the custom event proxy server with Spotlight for E2E test event capture. This eliminates race conditions by using Spotlight's reliable event streaming instead of the fragile timestamp-based filtering in the current proxy.
+todos:
+  - id: add-spotlight-dep
+    content: Add @spotlightjs/spotlight as devDependency to test-utils
+    status: completed
+  - id: create-spotlight-helpers
+    content: Create spotlight.ts with startSpotlight() and event waiting helpers
+    status: completed
+  - id: update-playwright-config
+    content: Add Spotlight support to getPlaywrightConfig()
+    status: completed
+  - id: migrate-first-app
+    content: Migrate react-router-7-lazy-routes as proof of concept
+    status: in_progress
+  - id: migrate-remaining
+    content: Migrate remaining ~106 test apps incrementally
+    status: pending
+  - id: cleanup-old-proxy
+    content: Remove deprecated event proxy code after full migration
+    status: pending
+---
+
+# Migrate E2E Tests from Event Proxy to Spotlight
+
+## Current Architecture
+
+```mermaid
+flowchart LR
+    subgraph current [Current Setup]
+        App[Test App] -->|"tunnel: localhost:3031"| Proxy[Event Proxy Server]
+        Proxy -->|Buffer + Timestamp Filter| Buffer[(Event Buffer)]
+        Test[Playwright Test] -->|waitForTransaction| Buffer
+    end
+```
+
+**Problems with current approach:**
+
+- Timestamp filtering has race conditions (stale events leak through)
+- Complex buffer management with timing edge cases
+- 108 test apps, ~162 files use `tunnel: localhost:3031`
+
+## Proposed Architecture
+
+```mermaid
+flowchart LR
+    subgraph proposed [Spotlight Setup]
+        App2[Test App] -->|"DSN: spotlight@localhost:PORT/0"| Spotlight[Spotlight Sidecar]
+        Spotlight -->|JSON Stream| Stream[(stdout/stderr)]
+        Test2[Playwright Test] -->|waitForTransaction| Stream
+    end
+```
+
+**Benefits:**
+
+- No timestamp filtering needed - Spotlight streams events in order
+- Production-tested event handling
+- Cleaner architecture with less custom code
+
+## Implementation Plan
+
+### Phase 1: Add Spotlight Infrastructure
+
+1. **Add `@spotlightjs/spotlight` dependency** to [`dev-packages/test-utils/package.json`](dev-packages/test-utils/package.json)
+
+2. **Create new Spotlight-based helpers** in [`dev-packages/test-utils/src/spotlight.ts`](dev-packages/test-utils/src/spotlight.ts):
+   - `startSpotlight(options)` - Spawns `spotlight run` with dynamic port, parses port from stderr
+   - `waitForSpotlightEvent(filter)` - Reads from Spotlight's JSON output stream
+   - `waitForTransaction()`, `waitForError()`, etc. - High-level wrappers matching current API
+
+3. **Update [`dev-packages/test-utils/src/playwright-config.ts`](dev-packages/test-utils/src/playwright-config.ts)**:
+   - Add option to use Spotlight instead of event proxy
+   - Configure webServer to run Spotlight with dynamic port
+   - Pass port via environment variable to test app
+
+### Phase 2: Create Migration Path
+
+4. **Design backward-compatible API**:
+   - Keep existing `waitForTransaction()` signature
+   - New implementation reads from Spotlight instead of HTTP streaming
+   - Port is passed via `SPOTLIGHT_PORT` env var
+
+5. **Update DSN handling in test apps**:
+   - Replace `tunnel: 'http://localhost:3031'` with DSN workaround
+   - DSN format: `http://spotlight@localhost:${SPOTLIGHT_PORT}/0`
+   - This makes SDK operate in "normal" mode (no tunnel)
+
+### Phase 3: Migrate Test Apps (Incremental)
+
+6. **Migration per test app involves**:
+   - Remove `start-event-proxy.mjs`
+   - Update `playwright.config.mjs` to use new Spotlight config
+   - Update Sentry init to use DSN workaround instead of tunnel
+   - No changes needed to test files (API stays the same)
+
+7. **Start with problematic apps**:
+   - `react-router-7-lazy-routes` (the failing one)
+   - `react-router-7-framework`
+   - Then expand to remaining ~106 apps
+
+### Phase 4: Cleanup
+
+8. **After all apps migrated**:
+   - Remove old event proxy code from `event-proxy-server.ts`
+   - Update documentation
+   - Remove unused dependencies
+
+## Key Technical Details
+
+### Port Extraction from Spotlight
+
+Spotlight outputs startup info to stderr. We parse it to get the dynamic port:
+
+```
+Spotlight listening on http://localhost:8969
+```
+
+### DSN Workaround Format
+
+Per [Spotlight docs](https://spotlightjs.com/docs/cli/run/#unsupported-sdks-dsn-workaround):
+
+```javascript
+Sentry.init({
+  dsn: `http://spotlight@localhost:${process.env.SPOTLIGHT_PORT}/0`,
+});
+```
+
+### Playwright Config Changes
+
+```javascript
+// Before
+webServer: [
+  { command: 'node start-event-proxy.mjs', port: 3031 },
+  { command: 'yarn start', port: 3030 },
+];
+
+// After - spotlight run auto-detects and runs the app
+webServer: [{ command: 'yarn spotlight run -p 0 -f json', port: 3030 }];
+```
+
+Note: `spotlight run` automatically:
+
+- Detects the start script from package.json (`dev`, `develop`, `serve`, `start`)
+- Starts the Spotlight sidecar on the specified port (or dynamic with `-p 0`)
+- Streams events to stdout in JSON format (with `-f json`)
+- Sets `SENTRY_SPOTLIGHT` env var for the child process

.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'
+      # Note: Spotlight env vars are NOT set globally - they should only be set
+      # in test apps that specifically test Spotlight functionality
       E2E_TEST_SENTRY_ORG_SLUG: 'sentry-javascript-sdks'
       E2E_TEST_SENTRY_PROJECT: 'sentry-javascript-e2e-tests'
     strategy:
@@ -988,6 +991,10 @@ jobs:
         run: yarn ci:copy-to-temp ./test-applications/${{ matrix.test-application }} ${{ runner.temp }}/test-application
         working-directory: dev-packages/e2e-tests
 
+      - name: Set Spotlight env var for spotlight tests
+        if: contains(matrix.test-application, 'spotlight')
+        run: echo "NEXT_PUBLIC_SENTRY_SPOTLIGHT=true" >> $GITHUB_ENV
+
       - name: Build E2E app
         working-directory: ${{ runner.temp }}/test-application
         timeout-minutes: 7
@@ -1060,6 +1067,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 }}
+      # Note: Spotlight env vars are NOT set globally - they should only be set
+      # in test apps that specifically test Spotlight functionality
       E2E_TEST_SENTRY_ORG_SLUG: 'sentry-javascript-sdks'
       E2E_TEST_SENTRY_PROJECT: 'sentry-javascript-e2e-tests'
     strategy:
@@ -1113,6 +1123,10 @@ jobs:
         run: yarn ci:copy-to-temp ./test-applications/${{ matrix.test-application }} ${{ runner.temp }}/test-application
         working-directory: dev-packages/e2e-tests
 
+      - name: Set Spotlight env var for spotlight tests
+        if: contains(matrix.test-application, 'spotlight')
+        run: echo "NEXT_PUBLIC_SENTRY_SPOTLIGHT=true" >> $GITHUB_ENV
+
       - name: Build E2E app
         working-directory: ${{ runner.temp }}/test-application
         timeout-minutes: 7

.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

@@ -173,6 +173,9 @@ 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,
+    // Note: Spotlight env vars (VITE_SENTRY_SPOTLIGHT, etc.) are NOT set globally.
+    // They should only be set in test apps that specifically test Spotlight functionality.
     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/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,