add subdomain to host the UI like drizzle studio

[betegon]

One more from @sergical

Drizzle has https://local.drizzle.studio/ - would be cool to have local.spotlightjs.com

you run it locally and it tells you to go to that url instead of localhost, just a very very far away nice-to-have i find delightful anytime i use drizzle

[BYK]

Feasibility of GitHub issue 994

Exported on 11/3/2025 at 10:42:05 GMT from Cursor (2.0.43)

---

User

Is this feasible: https://github.com/getsentry/spotlight/issues/994

---

Cursor

I'll investigate the feasibility of this feature by examining how Spotlight currently serves the overlay UI and understanding what would be needed to implement a local subdomain approach like Drizzle Studio.

Based on my investigation of the codebase and understanding how similar tools like Drizzle Studio implement this feature, yes, this is absolutely feasible!

Technical Feasibility Analysis

How It Works

The feature uses a DNS trick where a subdomain like local.spotlightjs.com is configured to resolve to 127.0.0.1 (localhost). When users access http://local.spotlightjs.com:8969, their browser resolves it to 127.0.0.1:8969, which is exactly where the Spotlight sidecar is running.

Current Architecture

Spotlight currently:

• Runs a sidecar server on localhost (default port 8969) using Hono
• Serves the overlay UI as static files from the sidecar
• Uses permissive CORS (cors() middleware with default settings) - this is crucial
• Logs: "Open http://localhost:8969 to see the Spotlight UI"

What's Required

1. DNS Configuration (Main requirement, outside codebase)

• Register/own spotlightjs.com domain
• Create DNS A record: local.spotlightjs.com → 127.0.0.1
• Or use wildcard: *.local.spotlightjs.com → 127.0.0.1 to support port-based subdomains like 8969.local.spotlightjs.com

2. Code Changes (Minimal, ~5-10 lines)

• Update logSpotlightUrl() in packages/sidecar/src/utils/extras.ts to use the new domain:

  export function logSpotlightUrl(port: number): void {
    logger.info(`Open http://local.spotlightjs.com:${port} to see the Spotlight UI`);
  }
  

• Optionally add a configuration option to toggle between localhost and the custom domain

3. Documentation Updates

• Update all references to localhost URLs in docs

Benefits

• ✅ More polished, branded developer experience
• ✅ Memorable URL that's easier to communicate
• ✅ Avoids localhost quirks in some browsers
• ✅ Professional appearance like other modern dev tools

Challenges

• ⚠️ Requires DNS setup (if domain not already owned)
• ⚠️ Users might initially be confused by the URL (though documentation helps)
• ⚠️ If using HTTPS, would need certificate handling (like mkcert for local dev)

Technical Compatibility

✅ CORS is already properly configured - The sidecar uses permissive CORS settings (line 33 in packages/sidecar/src/main.ts), so it will accept requests from any origin, including the custom subdomain.

Recommendation

This is a nice-to-have enhancement that would improve the developer experience with minimal code changes. The main blocker is the DNS configuration, which is a one-time setup if Getsentry already owns the spotlightjs.com domain (which seems likely given this is the project name).

The implementation effort is low (maybe 1-2 hours including testing and documentation), making this a great candidate for a quick win that improves polish and user experience.

     export function logSpotlightUrl(port: number): void {
       logger.info(`Open http://local.spotlightjs.com:${port} to see the Spotlight UI`);
     }

[BYK]

New plan: add a static HTML page that tries to include the script from http://localhost:8969 as in https://github.com/getsentry/spotlight/blob/main/packages/overlay/index.html like

<script type="module" crossorigin src="http://localhost:8969/assets/main.js"></script>

We may also add a fallback with the latest compiled version of the UI if the script load fails (indicating either spotlight is not running or it is running in sidecar-only mode, such as in the Electron app)