feat: Add __spotlight.initOptions and initialEvents (#515)

.changeset/ten-comics-guess.md

@@ -0,0 +1,8 @@
+---
+'@spotlightjs/overlay': minor
+'@spotlightjs/spotlight': minor
+---
+
+Add `__spotlight.initOptions` and initialEvents support allowing providing a list of "initial events" when Spotlight
+loads, not requiring the sidecar to be working. Mostly going to be used when replacing default error pages in
+frameworks.

packages/overlay/src/App.tsx

@@ -13,6 +13,8 @@ import type { NotificationCount, SpotlightOverlayOptions } from './types';
 type AppProps = Omit<SpotlightOverlayOptions, 'debug' | 'injectImmediately'> &
   Required<Pick<SpotlightOverlayOptions, 'sidecarUrl'>>;
 
+type EventData = { contentType: string; data: string | Uint8Array };
+
 export default function App({
   openOnInit = false,
   showTriggerButton = true,
@@ -21,6 +23,7 @@ export default function App({
   anchor,
   fullPage = false,
   showClearEventsButton = true,
+  initialEvents = {},
 }: AppProps) {
   const [integrationData, setIntegrationData] = useState<IntegrationData<unknown>>({});
   const [isOnline, setOnline] = useState(false);
@@ -141,7 +144,6 @@ export default function App({
       navigate(e.detail);
     };
 
-    type EventData = { contentType: string; data: string };
     const dispatchToContentTypeListener = ({ contentType, data }: EventData) => {
       const listener = contentTypeListeners[contentType];
       if (!listener) {
@@ -163,8 +165,16 @@ export default function App({
       }
     });
 
+    // Populate from initial events
+    for (const contentType in initialEvents) {
+      log(`Injecting initial events for ${contentType}`);
+      for (const data of initialEvents[contentType]) {
+        dispatchToContentTypeListener({ contentType, data });
+      }
+    }
+
     return { clearEvents, onEvent, onOpen, onClose, onNavigate, onToggle };
-  }, [integrations, navigate, sidecarUrl, contentTypeListeners]);
+  }, [integrations, navigate, sidecarUrl, contentTypeListeners, initialEvents]);
 
   useKeyPress('F12', ['ctrlKey'], eventHandlers.onToggle);
 

packages/overlay/src/index.tsx

@@ -60,7 +60,7 @@ export async function onClose(cb: EventListener) {
 /**
  * Send an event to spotlight without the sidecar
  */
-export async function sendEvent(contentType: string, data: string) {
+export async function sendEvent(contentType: string, data: string | Uint8Array) {
   trigger('event', { contentType, data });
 }
 
@@ -88,18 +88,21 @@ function isSpotlightInjected() {
   return false;
 }
 
-export async function init({
-  openOnInit = false,
-  showTriggerButton = true,
-  injectImmediately = false,
-  sidecarUrl = DEFAULT_SIDECAR_URL,
-  anchor = DEFAULT_ANCHOR,
-  debug = false,
-  integrations,
-  experiments = DEFAULT_EXPERIMENTS,
-  fullPage = false,
-  showClearEventsButton = true,
-}: SpotlightOverlayOptions = {}) {
+export async function init(
+  {
+    openOnInit = false,
+    showTriggerButton = true,
+    injectImmediately = false,
+    sidecarUrl = DEFAULT_SIDECAR_URL,
+    anchor = DEFAULT_ANCHOR,
+    debug = false,
+    integrations,
+    experiments = DEFAULT_EXPERIMENTS,
+    fullPage = false,
+    showClearEventsButton = true,
+    initialEvents = undefined,
+  }: SpotlightOverlayOptions = (window as WindowWithSpotlight).__spotlight?.initOptions || {},
+) {
   // The undefined document guard is to avoid being initialized in a Worker
   // @see https://github.com/vitejs/vite/discussions/17644#discussioncomment-10026390
   if (typeof document === 'undefined') return;
@@ -173,6 +176,7 @@ export async function init({
           anchor={anchor}
           fullPage={fullPage}
           showClearEventsButton={showClearEventsButton}
+          initialEvents={initialEvents}
         />
       </SpotlightContextProvider>
     </MemoryRouter>,

packages/overlay/src/types.ts

@@ -1,4 +1,4 @@
-import { type Integration } from './integrations/integration';
+import type { Integration } from './integrations/integration';
 
 export type ExperimentName = 'sentry:focus-local-events';
 
@@ -86,7 +86,7 @@ export type SpotlightOverlayOptions = {
   /**
    * If set to `true`, the Spotlight overlay will be rendered in full page mode.
    * It can't be closed nor minimized.
-   * This is useful for replaceing error page or in when directly rendered as an html page
+   * This is useful for replacing error page or in when directly rendered as an html page
    */
   fullPage?: boolean;
 
@@ -97,6 +97,13 @@ export type SpotlightOverlayOptions = {
    * @default true
    */
   showClearEventsButton?: boolean;
+
+  /**
+   * Events to be sent into Spotlight (bypassing the sidecar) right after init
+   *
+   * This is useful when replacing error pages of frameworks etc. Implies "injectImmediately".
+   */
+  initialEvents?: Record<string, (string | Uint8Array)[]>;
 };
 
 export type NotificationCount = {
@@ -115,5 +122,6 @@ export type NotificationCount = {
 export type WindowWithSpotlight = Window & {
   __spotlight?: {
     eventTarget?: EventTarget;
+    initOptions?: SpotlightOverlayOptions;
   };
 };