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

## Problem

The Spotlight configuration logic had a precedence bug where when
`spotlight: true` was set in config AND the `SENTRY_SPOTLIGHT`
environment variable contained a URL string, the SDK would incorrectly
use `true` instead of the URL from the environment variable.

According to the [Spotlight
specification](https://raw.githubusercontent.com/getsentry/sentry-docs/b38e3b307f900665a348f855559ac1d1c58914cc/develop-docs/sdk/expected-features/spotlight.mdx),
when `spotlight: true` is set and the env var contains a URL, the URL
from the env var should be used to allow developers to override the
Spotlight URL via environment variables.

**Previous behavior:**
```typescript
// Config: spotlight: true
// Env: SENTRY_SPOTLIGHT=http://custom:3000/stream
// Result: spotlight = true ❌ (incorrect)
```

**Expected behavior per spec:**
```typescript
// Config: spotlight: true
// Env: SENTRY_SPOTLIGHT=http://custom:3000/stream
// Result: spotlight = "http://custom:3000/stream" ✅ (correct)
```

## Solution

Fixed the precedence logic in `getClientOptions()` to properly implement
the specification:

1. `spotlight: false` → Always disabled (overrides env var)
2. `spotlight: string` → Uses the config URL (ignores env var)
3. `spotlight: true` + env var URL → **Uses the env var URL** (the bug
fix)
4. `spotlight: true` + env var truthy → Uses default URL
5. No config + env var → Parses and uses env var

The implementation reuses the existing `envToBool()` utility to avoid
code duplication.

## Changes

- Fixed Spotlight precedence logic in
`packages/node-core/src/sdk/index.ts`
- Added 12 comprehensive test cases covering all precedence scenarios in
`packages/node-core/test/sdk/init.test.ts`
- Updated CHANGELOG.md

## Test Coverage

The new tests cover:
- ✅ Env var only: truthy values, falsy values, URL strings
- ✅ Config only: `true`, `false`, URL string
- ✅ Precedence: config `false` overrides env var (URL, truthy, falsy)
- ✅ Precedence: config URL overrides env var
- ✅ Precedence: config `true` + env var URL uses env var URL (the fix)
- ✅ Precedence: config `true` + env var truthy uses default URL

## Related

- Original Spotlight implementation: #13325
- Spotlight specification: https://spotlightjs.com/

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>

Author: BYK

.size-limit.js

@@ -240,7 +240,7 @@ module.exports = [
     import: createImport('init'),
     ignore: [...builtinModules, ...nodePrefixedBuiltinModules],
     gzip: true,
-    limit: '158 KB',
+    limit: '160 KB',
   },
   {
     name: '@sentry/node - without tracing',

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 (#18195)
 
 ## 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,114 @@ describe('init()', () => {
         }),
       );
     });
+
+    describe('spotlight configuration', () => {
+      afterEach(() => {
+        delete process.env.SENTRY_SPOTLIGHT;
+      });
+
+      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);
+      });
+    });
   });
 });