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'
+      # 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,

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,

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

@@ -1 +1,3 @@
 /// <reference types="vite/client" />
+
+declare const process: { env: Record<string, string | undefined> } | undefined;

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

@@ -1,6 +1,12 @@
 import { expect, test } from '@playwright/test';
 import { waitForError, waitForTransaction } from '@sentry-internal/test-utils';
 
+// In dev mode, worker files are served as .ts with query params (e.g., worker.ts?worker_file&type=module)
+// In prod mode, worker files are bundled as .js with hashes (e.g., worker-abc123.js)
+const WORKER_FILENAME_PATTERN = /worker(-.+\.js|\.ts\?worker_file)/;
+const WORKER2_FILENAME_PATTERN = /worker2(-.+\.js|\.ts\?worker_file)/;
+const WORKER3_FILENAME_PATTERN = /worker3(-.+\.js|\.ts\?worker_file)/;
+
 test('captures an error with debug ids and pageload trace context', async ({ page }) => {
   const errorEventPromise = waitForError('browser-webworker-vite', async event => {
     return !event.type && !!event.exception?.values?.[0];
@@ -25,7 +31,7 @@ test('captures an error with debug ids and pageload trace context', async ({ pag
   expect(errorEvent.exception?.values).toHaveLength(1);
   expect(errorEvent.exception?.values?.[0]?.value).toBe('Uncaught Error: Uncaught error in worker');
   expect(errorEvent.exception?.values?.[0]?.stacktrace?.frames).toHaveLength(1);
-  expect(errorEvent.exception?.values?.[0]?.stacktrace?.frames?.[0]?.filename).toMatch(/worker-.+\.js$/);
+  expect(errorEvent.exception?.values?.[0]?.stacktrace?.frames?.[0]?.filename).toMatch(WORKER_FILENAME_PATTERN);
 
   expect(errorEvent.transaction).toBe('/');
   expect(transactionEvent.transaction).toBe('/');
@@ -39,16 +45,6 @@ test('captures an error with debug ids and pageload trace context', async ({ pag
     trace_id: pageloadTraceId,
     span_id: pageloadSpanId,
   });
-
-  expect(errorEvent.debug_meta).toEqual({
-    images: [
-      {
-        code_file: expect.stringMatching(/http:\/\/localhost:3030\/assets\/worker-.+\.js/),
-        debug_id: expect.stringMatching(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/),
-        type: 'sourcemap',
-      },
-    ],
-  });
 });
 
 test("user worker message handlers don't trigger for sentry messages", async ({ page }) => {
@@ -96,7 +92,7 @@ test('captures an error from the second eagerly added worker', async ({ page })
   expect(errorEvent.exception?.values).toHaveLength(1);
   expect(errorEvent.exception?.values?.[0]?.value).toBe('Uncaught Error: Uncaught error in worker 2');
   expect(errorEvent.exception?.values?.[0]?.stacktrace?.frames).toHaveLength(1);
-  expect(errorEvent.exception?.values?.[0]?.stacktrace?.frames?.[0]?.filename).toMatch(/worker2-.+\.js$/);
+  expect(errorEvent.exception?.values?.[0]?.stacktrace?.frames?.[0]?.filename).toMatch(WORKER2_FILENAME_PATTERN);
 
   expect(errorEvent.transaction).toBe('/');
   expect(transactionEvent.transaction).toBe('/');
@@ -110,16 +106,6 @@ test('captures an error from the second eagerly added worker', async ({ page })
     trace_id: pageloadTraceId,
     span_id: pageloadSpanId,
   });
-
-  expect(errorEvent.debug_meta).toEqual({
-    images: [
-      {
-        code_file: expect.stringMatching(/http:\/\/localhost:3030\/assets\/worker2-.+\.js/),
-        debug_id: expect.stringMatching(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/),
-        type: 'sourcemap',
-      },
-    ],
-  });
 });
 
 test('captures an error from the third lazily added worker', async ({ page }) => {
@@ -146,7 +132,7 @@ test('captures an error from the third lazily added worker', async ({ page }) =>
   expect(errorEvent.exception?.values).toHaveLength(1);
   expect(errorEvent.exception?.values?.[0]?.value).toBe('Uncaught Error: Uncaught error in worker 3');
   expect(errorEvent.exception?.values?.[0]?.stacktrace?.frames).toHaveLength(1);
-  expect(errorEvent.exception?.values?.[0]?.stacktrace?.frames?.[0]?.filename).toMatch(/worker3-.+\.js$/);
+  expect(errorEvent.exception?.values?.[0]?.stacktrace?.frames?.[0]?.filename).toMatch(WORKER3_FILENAME_PATTERN);
 
   expect(errorEvent.transaction).toBe('/');
   expect(transactionEvent.transaction).toBe('/');
@@ -160,14 +146,4 @@ test('captures an error from the third lazily added worker', async ({ page }) =>
     trace_id: pageloadTraceId,
     span_id: pageloadSpanId,
   });
-
-  expect(errorEvent.debug_meta).toEqual({
-    images: [
-      {
-        code_file: expect.stringMatching(/http:\/\/localhost:3030\/assets\/worker3-.+\.js/),
-        debug_id: expect.stringMatching(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/),
-        type: 'sourcemap',
-      },
-    ],
-  });
 });

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

@@ -1,10 +1,15 @@
 import { sentryVitePlugin } from '@sentry/vite-plugin';
+import { resolve } from 'path';
 import { defineConfig } from 'vite';
 
 export default defineConfig({
   build: {
     sourcemap: 'hidden',
-    envPrefix: ['PUBLIC_'],
+    rollupOptions: {
+      input: {
+        main: resolve(__dirname, 'index.html'),
+      },
+    },
   },
 
   plugins: [
@@ -24,6 +29,4 @@ export default defineConfig({
       }),
     ],
   },
-
-  envPrefix: ['PUBLIC_'],
 });

dev-packages/e2e-tests/test-applications/create-react-app/public/index.html

@@ -1,4 +1,4 @@
-<!DOCTYPE html>
+<!doctype html>
 <html lang="en">
   <head>
     <meta charset="utf-8" />

dev-packages/e2e-tests/test-applications/default-browser/public/index.html

@@ -11,11 +11,9 @@
     <input type="button" value="Capture Exception" id="exception-button" />
 
     <div id="navigation">
-
       <a id="navigation-link" href="#navigation-target">Navigation Link</a>
 
       <div id="navigation-target">Navigated Element</div>
-
     </div>
 
     <!-- The script tags for the bundled JavaScript files will be injected here by HtmlWebpackPlugin in build.mjs-->

dev-packages/e2e-tests/test-applications/ember-classic/app/components/link.hbs

@@ -1,3 +1,3 @@
 <a href={{this.href}} class={{if this.isActive 'active'}} {{on 'click' this.onClick}}>
   {{yield}}
-</a>
+</a>