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

.size-limit.js

@@ -8,7 +8,7 @@ module.exports = [
     path: 'packages/browser/build/npm/esm/prod/index.js',
     import: createImport('init'),
     gzip: true,
-    limit: '25 KB',
+    limit: '25.5 KB',
   },
   {
     name: '@sentry/browser - with treeshaking flags',
@@ -38,7 +38,7 @@ module.exports = [
     path: 'packages/browser/build/npm/esm/prod/index.js',
     import: createImport('init', 'browserTracingIntegration'),
     gzip: true,
-    limit: '42 KB',
+    limit: '42.5 KB',
   },
   {
     name: '@sentry/browser (incl. Tracing, Profiling)',
@@ -82,7 +82,7 @@ module.exports = [
     path: 'packages/browser/build/npm/esm/prod/index.js',
     import: createImport('init', 'browserTracingIntegration', 'replayIntegration', 'replayCanvasIntegration'),
     gzip: true,
-    limit: '85 KB',
+    limit: '86 KB',
   },
   {
     name: '@sentry/browser (incl. Tracing, Replay, Feedback)',
@@ -140,15 +140,15 @@ module.exports = [
     import: createImport('init', 'ErrorBoundary'),
     ignore: ['react/jsx-runtime'],
     gzip: true,
-    limit: '27 KB',
+    limit: '27.5 KB',
   },
   {
     name: '@sentry/react (incl. Tracing)',
     path: 'packages/react/build/esm/index.js',
     import: createImport('init', 'ErrorBoundary', 'reactRouterV6BrowserTracingIntegration'),
     ignore: ['react/jsx-runtime'],
     gzip: true,
-    limit: '44 KB',
+    limit: '45 KB',
   },
   // Vue SDK (ESM)
   {
@@ -163,28 +163,28 @@ module.exports = [
     path: 'packages/vue/build/esm/index.js',
     import: createImport('init', 'browserTracingIntegration'),
     gzip: true,
-    limit: '44 KB',
+    limit: '44.5 KB',
   },
   // Svelte SDK (ESM)
   {
     name: '@sentry/svelte',
     path: 'packages/svelte/build/esm/index.js',
     import: createImport('init'),
     gzip: true,
-    limit: '25 KB',
+    limit: '25.6 KB',
   },
   // Browser CDN bundles
   {
     name: 'CDN Bundle',
     path: createCDNPath('bundle.min.js'),
     gzip: true,
-    limit: '27.5 KB',
+    limit: '28 KB',
   },
   {
     name: 'CDN Bundle (incl. Tracing)',
     path: createCDNPath('bundle.tracing.min.js'),
     gzip: true,
-    limit: '42.5 KB',
+    limit: '43 KB',
   },
   {
     name: 'CDN Bundle (incl. Tracing, Replay)',
@@ -234,7 +234,7 @@ module.exports = [
     import: createImport('init'),
     ignore: ['next/router', 'next/constants'],
     gzip: true,
-    limit: '46.5 KB',
+    limit: '47 KB',
   },
   // SvelteKit SDK (ESM)
   {
@@ -243,7 +243,7 @@ module.exports = [
     import: createImport('init'),
     ignore: ['$app/stores'],
     gzip: true,
-    limit: '42 KB',
+    limit: '43 KB',
   },
   // Node-Core SDK (ESM)
   {

dev-packages/bundler-tests/tests/bundling.test.ts

@@ -136,9 +136,52 @@ describe('spotlight', () => {
       expect(code).toContain(SPOTLIGHT_URL);
     });
 
-    test(`${name} production bundle does not contain spotlight`, async () => {
+    // Spotlight is now included in production builds too (not dev-only)
+    // The integration is gated by the spotlight option, so there's no need
+    // to strip it from production builds
+    test(`${name} production bundle contains spotlight`, async () => {
       const code = await bundler('production');
-      expect(code).not.toContain(SPOTLIGHT_URL);
+      expect(code).toContain(SPOTLIGHT_URL);
     });
   }
 });
+
+describe('__VITE_SPOTLIGHT_ENV__ rollup replacement', () => {
+  // Test that our rollup build correctly replaces __VITE_SPOTLIGHT_ENV__
+  // ESM bundles should have import.meta.env access, CJS should have undefined
+
+  function readSdkFile(packageName: string, format: 'esm' | 'cjs'): string {
+    const sdkPath = path.join(rootDir(), 'packages', packageName, 'build', format, 'sdk.js');
+    if (!fs.existsSync(sdkPath)) {
+      throw new Error(`SDK file not found: ${sdkPath}. Make sure to run yarn build:dev first.`);
+    }
+    return fs.readFileSync(sdkPath, 'utf8');
+  }
+
+  // Remove comments from code to test only actual code
+  function stripComments(code: string): string {
+    // Remove single-line comments
+    return code.replace(/\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '');
+  }
+
+  test.each(['react', 'vue', 'svelte', 'solid'] as const)(
+    '%s ESM bundle contains import.meta.env.VITE_SENTRY_SPOTLIGHT access',
+    packageName => {
+      const code = stripComments(readSdkFile(packageName, 'esm'));
+      // ESM bundles should have import.meta.env access for Vite support
+      // The replacement is: import.meta.env.VITE_SENTRY_SPOTLIGHT (without optional chaining)
+      // so that Vite can properly do static replacement at build time
+      expect(code).toMatch(/import\.meta\.env\.[A-Z_]+SPOTLIGHT/);
+    },
+  );
+
+  test.each(['react', 'vue', 'svelte', 'solid'] as const)(
+    '%s CJS bundle does not contain import.meta.env (CJS incompatible)',
+    packageName => {
+      const code = stripComments(readSdkFile(packageName, 'cjs'));
+      // CJS bundles should NOT have import.meta.env as it's ESM-only syntax
+      // The __VITE_SPOTLIGHT_ENV__ placeholder should be replaced with 'undefined'
+      expect(code).not.toMatch(/import\.meta\.env/);
+    },
+  );
+});

dev-packages/e2e-tests/test-applications/browser-spotlight/.npmrc

@@ -0,0 +1,2 @@
+@sentry:registry=http://127.0.0.1:4873
+@sentry-internal:registry=http://127.0.0.1:4873

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

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Spotlight E2E Test</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

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

@@ -0,0 +1,29 @@
+{
+  "name": "browser-spotlight-test-app",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "VITE_SENTRY_SPOTLIGHT=http://localhost:3032/stream VITE_E2E_TEST_DSN=${E2E_TEST_DSN:-https://public@dsn.ingest.sentry.io/1234567} vite build",
+    "preview": "vite preview --port 3030",
+    "test": "playwright test",
+    "clean": "npx rimraf node_modules pnpm-lock.yaml",
+    "test:build": "pnpm install && pnpm build",
+    "test:assert": "pnpm test"
+  },
+  "dependencies": {
+    "@sentry/react": "latest || *",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "~1.56.0",
+    "@sentry-internal/test-utils": "link:../../../test-utils",
+    "@vitejs/plugin-react": "^4.2.1",
+    "vite": "~5.4.0"
+  },
+  "volta": {
+    "extends": "../../package.json"
+  }
+}

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

@@ -0,0 +1,16 @@
+import { getPlaywrightConfig } from '@sentry-internal/test-utils';
+
+const config = getPlaywrightConfig({
+  startCommand: `pnpm preview`,
+});
+
+// Add the Spotlight proxy server as an additional webServer
+// This runs alongside the main event proxy and app server
+config.webServer.push({
+  command: 'node start-spotlight-proxy.mjs',
+  port: 3032,
+  stdout: 'pipe',
+  stderr: 'pipe',
+});
+
+export default config;

dev-packages/e2e-tests/test-applications/browser-spotlight/src/main.jsx

@@ -0,0 +1,65 @@
+import * as Sentry from '@sentry/react';
+
+// Debug: Log env vars
+console.log('[E2E Debug] VITE_SENTRY_SPOTLIGHT:', import.meta.env.VITE_SENTRY_SPOTLIGHT);
+console.log('[E2E Debug] VITE_E2E_TEST_DSN:', import.meta.env.VITE_E2E_TEST_DSN);
+console.log('[E2E Debug] MODE:', import.meta.env.MODE);
+
+// Debug: Check if import.meta.env is available at runtime
+console.log('[E2E Debug] typeof import.meta:', typeof import.meta);
+console.log('[E2E Debug] typeof import.meta.env:', typeof import.meta.env);
+console.log('[E2E Debug] import.meta.env object:', JSON.stringify(import.meta.env));
+
+// Initialize Sentry - the @sentry/react SDK automatically parses
+// VITE_SENTRY_SPOTLIGHT from import.meta.env (zero-config for Vite!)
+const initOptions = {
+  dsn: import.meta.env.VITE_E2E_TEST_DSN,
+  integrations: [Sentry.browserTracingIntegration()],
+  tracesSampleRate: 1.0,
+  release: 'e2e-test',
+  environment: 'qa',
+  // Use tunnel to capture events at our proxy server
+  tunnel: 'http://localhost:3031',
+  debug: true,
+};
+
+console.log(
+  '[E2E Debug] Init options BEFORE Sentry.init:',
+  JSON.stringify({
+    dsn: initOptions.dsn,
+    spotlight: initOptions.spotlight,
+    debug: initOptions.debug,
+  }),
+);
+
+const client = Sentry.init(initOptions);
+
+// Debug: Check what the client received
+const clientOptions = client?.getOptions();
+console.log(
+  '[E2E Debug] Client options AFTER Sentry.init:',
+  JSON.stringify({
+    dsn: clientOptions?.dsn,
+    spotlight: clientOptions?.spotlight,
+    debug: clientOptions?.debug,
+  }),
+);
+
+// Debug: Check if Spotlight integration was added
+const integrations = clientOptions?.integrations || [];
+const integrationNames = integrations.map(i => i.name);
+console.log('[E2E Debug] Integrations:', integrationNames.join(', '));
+console.log('[E2E Debug] Has SpotlightBrowser:', integrationNames.includes('SpotlightBrowser'));
+
+// Simple render
+document.getElementById('root').innerHTML = `
+  <div>
+    <h1>Spotlight E2E Test</h1>
+    <p>This page tests that VITE_SENTRY_SPOTLIGHT env var enables Spotlight integration.</p>
+    <button id="exception-button">Trigger Error</button>
+  </div>
+`;
+
+document.getElementById('exception-button').addEventListener('click', () => {
+  throw new Error('Spotlight test error!');
+});

dev-packages/e2e-tests/test-applications/browser-spotlight/start-event-proxy.mjs

@@ -0,0 +1,7 @@
+import { startEventProxyServer } from '@sentry-internal/test-utils';
+
+// Start the main event proxy server that captures events via tunnel
+startEventProxyServer({
+  port: 3031,
+  proxyServerName: 'browser-spotlight',
+});

dev-packages/e2e-tests/test-applications/browser-spotlight/start-spotlight-proxy.mjs

@@ -0,0 +1,16 @@
+import { startSpotlightProxyServer } from '@sentry-internal/test-utils';
+
+console.log('[Spotlight Proxy] Starting spotlight proxy server on port 3032...');
+
+// Start a Spotlight proxy server that captures events sent to /stream
+// This simulates the Spotlight sidecar and allows us to verify events arrive
+startSpotlightProxyServer({
+  port: 3032,
+  proxyServerName: 'browser-spotlight-sidecar',
+})
+  .then(() => {
+    console.log('[Spotlight Proxy] Server started successfully on port 3032');
+  })
+  .catch(err => {
+    console.error('[Spotlight Proxy] Failed to start server:', err);
+  });

dev-packages/e2e-tests/test-applications/browser-spotlight/tests/spotlight.test.ts

@@ -0,0 +1,80 @@
+import { expect, test } from '@playwright/test';
+import { waitForError, waitForSpotlightError, waitForSpotlightTransaction } from '@sentry-internal/test-utils';
+
+// Forward browser console messages to the test output for debugging
+test.beforeEach(async ({ page }) => {
+  page.on('console', msg => {
+    console.log(`[Browser Console] ${msg.type()}: ${msg.text()}`);
+  });
+  page.on('pageerror', error => {
+    console.log(`[Browser Error] ${error.message}`);
+  });
+});
+
+/**
+ * Test that VITE_SENTRY_SPOTLIGHT environment variable automatically enables Spotlight.
+ *
+ * This test verifies that:
+ * 1. The SDK automatically parses VITE_SENTRY_SPOTLIGHT env var via import.meta.env
+ * 2. The SDK enables Spotlight WITHOUT explicit configuration (zero-config for Vite!)
+ * 3. Events are sent to both the tunnel AND the Spotlight sidecar URL
+ *
+ * IMPORTANT: The test app does NOT explicitly add spotlightBrowserIntegration.
+ * The SDK should automatically enable Spotlight when VITE_SENTRY_SPOTLIGHT is set.
+ *
+ * Test setup:
+ * - VITE_SENTRY_SPOTLIGHT is set to 'http://localhost:3032/stream' at build time
+ * - tunnel is set to 'http://localhost:3031' for regular event capture
+ * - A Spotlight proxy server runs on port 3032 to capture Spotlight events
+ * - A regular event proxy server runs on port 3031 to capture tunnel events
+ */
+test('VITE_SENTRY_SPOTLIGHT env var automatically enables Spotlight', async ({ page }) => {
+  // Wait for the error to arrive at the regular tunnel (port 3031)
+  const tunnelErrorPromise = waitForError('browser-spotlight', event => {
+    return !event.type && event.exception?.values?.[0]?.value === 'Spotlight test error!';
+  });
+
+  // Wait for the error event to arrive at the Spotlight sidecar (port 3032)
+  const spotlightErrorPromise = waitForSpotlightError('browser-spotlight-sidecar', event => {
+    return !event.type && event.exception?.values?.[0]?.value === 'Spotlight test error!';
+  });
+
+  await page.goto('/');
+
+  const exceptionButton = page.locator('id=exception-button');
+  await exceptionButton.click();
+
+  // Both promises should resolve - the error should be sent to BOTH destinations
+  const [tunnelError, spotlightError] = await Promise.all([tunnelErrorPromise, spotlightErrorPromise]);
+
+  // Verify the Spotlight sidecar received the error
+  expect(spotlightError.exception?.values).toHaveLength(1);
+  expect(spotlightError.exception?.values?.[0]?.value).toBe('Spotlight test error!');
+  expect(spotlightError.exception?.values?.[0]?.type).toBe('Error');
+
+  // Verify the tunnel also received the error (normal Sentry flow still works)
+  expect(tunnelError.exception?.values).toHaveLength(1);
+  expect(tunnelError.exception?.values?.[0]?.value).toBe('Spotlight test error!');
+
+  // Both events should have the same trace context
+  expect(spotlightError.contexts?.trace?.trace_id).toBe(tunnelError.contexts?.trace?.trace_id);
+});
+
+/**
+ * Test that Spotlight automatically receives transaction events.
+ */
+test('VITE_SENTRY_SPOTLIGHT automatically sends transactions to sidecar', async ({ page }) => {
+  // Wait for a pageload transaction to arrive at the Spotlight sidecar
+  const spotlightTransactionPromise = waitForSpotlightTransaction('browser-spotlight-sidecar', event => {
+    return event.type === 'transaction' && event.contexts?.trace?.op === 'pageload';
+  });
+
+  await page.goto('/');
+
+  const spotlightTransaction = await spotlightTransactionPromise;
+
+  // Verify the Spotlight sidecar received the transaction
+  expect(spotlightTransaction.type).toBe('transaction');
+  expect(spotlightTransaction.contexts?.trace?.op).toBe('pageload');
+  expect(spotlightTransaction.transaction).toBe('/');
+});

dev-packages/e2e-tests/test-applications/browser-spotlight/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "target": "ESNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["tests/**/*.ts"]
+}