fix(node): Fix Spotlight configuration precedence to match specification

The Spotlight configuration logic had a precedence bug where when
'spotlight: true' was set AND the 'SENTRY_SPOTLIGHT' env var contained
a URL string, the SDK would use 'true' instead of the URL from the env var.

According to the Spotlight specification, when 'spotlight: true' is set
and the env var contains a URL, the URL should be used.

Changes:
- Fixed precedence logic in getClientOptions() to properly handle the
  case where config is 'true' and env var is a URL string
- Added 12 comprehensive test cases covering all precedence scenarios
- Reused existing envToBool() utility for env var parsing

Fixes the issue where developers couldn't override the Spotlight URL
via environment variable when using 'spotlight: true' in config.

Author: BYK

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## Unreleased
 
-- "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
+- fix(node): Fix Spotlight configuration precedence to match specification (#18160)
 
 ## 10.25.0
 

packages/node-core/src/sdk/index.ts

@@ -182,8 +182,24 @@ function getClientOptions(
   getDefaultIntegrationsImpl: (options: Options) => Integration[],
 ): NodeClientOptions {
   const release = getRelease(options.release);
-  const spotlight =
-    options.spotlight ?? envToBool(process.env.SENTRY_SPOTLIGHT, { strict: true }) ?? process.env.SENTRY_SPOTLIGHT;
+
+  // Parse spotlight configuration with proper precedence per spec
+  let spotlight: boolean | string | undefined;
+  if (options.spotlight === false) {
+    spotlight = false;
+  } else if (typeof options.spotlight === 'string') {
+    spotlight = options.spotlight;
+  } else {
+    // options.spotlight is true or undefined
+    const envBool = envToBool(process.env.SENTRY_SPOTLIGHT, { strict: true });
+    const envUrl = envBool === null && process.env.SENTRY_SPOTLIGHT ? process.env.SENTRY_SPOTLIGHT : undefined;
+
+    spotlight =
+      options.spotlight === true
+        ? (envUrl ?? true) // true: use env URL if present, otherwise true
+        : (envBool ?? envUrl); // undefined: use env var (bool or URL)
+  }
+
   const tracesSampleRate = getTracesSampleRate(options.tracesSampleRate);
 
   const mergedOptions = {

packages/node-core/test/sdk/init.test.ts

@@ -216,6 +216,110 @@ describe('init()', () => {
         }),
       );
     });
+
+    describe('spotlight configuration', () => {
+      it('enables spotlight with default URL from `SENTRY_SPOTLIGHT` env variable (truthy value)', () => {
+        process.env.SENTRY_SPOTLIGHT = 'true';
+
+        const client = init({ dsn: PUBLIC_DSN });
+
+        expect(client?.getOptions().spotlight).toBe(true);
+        expect(client?.getOptions().integrations.some(integration => integration.name === 'Spotlight')).toBe(true);
+      });
+
+      it('disables spotlight from `SENTRY_SPOTLIGHT` env variable (falsy value)', () => {
+        process.env.SENTRY_SPOTLIGHT = 'false';
+
+        const client = init({ dsn: PUBLIC_DSN });
+
+        expect(client?.getOptions().spotlight).toBe(false);
+        expect(client?.getOptions().integrations.some(integration => integration.name === 'Spotlight')).toBe(false);
+      });
+
+      it('enables spotlight with custom URL from `SENTRY_SPOTLIGHT` env variable', () => {
+        process.env.SENTRY_SPOTLIGHT = 'http://localhost:3000/stream';
+
+        const client = init({ dsn: PUBLIC_DSN });
+
+        expect(client?.getOptions().spotlight).toBe('http://localhost:3000/stream');
+        expect(client?.getOptions().integrations.some(integration => integration.name === 'Spotlight')).toBe(true);
+      });
+
+      it('enables spotlight with default URL from config `true`', () => {
+        const client = init({ dsn: PUBLIC_DSN, spotlight: true });
+
+        expect(client?.getOptions().spotlight).toBe(true);
+        expect(client?.getOptions().integrations.some(integration => integration.name === 'Spotlight')).toBe(true);
+      });
+
+      it('disables spotlight from config `false`', () => {
+        const client = init({ dsn: PUBLIC_DSN, spotlight: false });
+
+        expect(client?.getOptions().spotlight).toBe(false);
+        expect(client?.getOptions().integrations.some(integration => integration.name === 'Spotlight')).toBe(false);
+      });
+
+      it('enables spotlight with custom URL from config', () => {
+        const client = init({ dsn: PUBLIC_DSN, spotlight: 'http://custom:8888/stream' });
+
+        expect(client?.getOptions().spotlight).toBe('http://custom:8888/stream');
+        expect(client?.getOptions().integrations.some(integration => integration.name === 'Spotlight')).toBe(true);
+      });
+
+      it('config `false` overrides `SENTRY_SPOTLIGHT` env variable URL', () => {
+        process.env.SENTRY_SPOTLIGHT = 'http://localhost:3000/stream';
+
+        const client = init({ dsn: PUBLIC_DSN, spotlight: false });
+
+        expect(client?.getOptions().spotlight).toBe(false);
+        expect(client?.getOptions().integrations.some(integration => integration.name === 'Spotlight')).toBe(false);
+      });
+
+      it('config `false` overrides `SENTRY_SPOTLIGHT` env variable truthy value', () => {
+        process.env.SENTRY_SPOTLIGHT = 'true';
+
+        const client = init({ dsn: PUBLIC_DSN, spotlight: false });
+
+        expect(client?.getOptions().spotlight).toBe(false);
+        expect(client?.getOptions().integrations.some(integration => integration.name === 'Spotlight')).toBe(false);
+      });
+
+      it('config `false` with `SENTRY_SPOTLIGHT` env variable falsy value keeps spotlight disabled', () => {
+        process.env.SENTRY_SPOTLIGHT = 'false';
+
+        const client = init({ dsn: PUBLIC_DSN, spotlight: false });
+
+        expect(client?.getOptions().spotlight).toBe(false);
+        expect(client?.getOptions().integrations.some(integration => integration.name === 'Spotlight')).toBe(false);
+      });
+
+      it('config URL overrides `SENTRY_SPOTLIGHT` env variable URL', () => {
+        process.env.SENTRY_SPOTLIGHT = 'http://env:3000/stream';
+
+        const client = init({ dsn: PUBLIC_DSN, spotlight: 'http://config:8888/stream' });
+
+        expect(client?.getOptions().spotlight).toBe('http://config:8888/stream');
+        expect(client?.getOptions().integrations.some(integration => integration.name === 'Spotlight')).toBe(true);
+      });
+
+      it('config `true` with env var URL uses env var URL', () => {
+        process.env.SENTRY_SPOTLIGHT = 'http://localhost:3000/stream';
+
+        const client = init({ dsn: PUBLIC_DSN, spotlight: true });
+
+        expect(client?.getOptions().spotlight).toBe('http://localhost:3000/stream');
+        expect(client?.getOptions().integrations.some(integration => integration.name === 'Spotlight')).toBe(true);
+      });
+
+      it('config `true` with env var truthy value uses default URL', () => {
+        process.env.SENTRY_SPOTLIGHT = 'true';
+
+        const client = init({ dsn: PUBLIC_DSN, spotlight: true });
+
+        expect(client?.getOptions().spotlight).toBe(true);
+        expect(client?.getOptions().integrations.some(integration => integration.name === 'Spotlight')).toBe(true);
+      });
+    });
   });
 });