Skip to content

Write your own Integration

An integration in Spotlight is rather powerful. It can completely change the behavior, add, remove functionality from Spotlight.

Integration Ordering

All integrations are run in the order that they are configured. For instance, for the array [sentry(), astro()] in the init call, sentry() will run before astro() and astro might overwrite things perviously configured.

Your integration should ideally be able to run in any order. If this isn’t possible, we recommend documenting that your integration needs to come first or last in your user’s integrations configuration array.

Explaining the Sentry Integration

so you can write your own

First the integration needs a name name: 'sentry'.


Next up, we have an optional function that is invoked during initialization of Spotlight called setup. In Sentry’s case we try to find a running Browser SDK and hook into it to tell it to send events to the Sidecar.

How does an integration receive events?

It receives an event depending on a list of compatible headers, e.g for Sentry Integration: forwardedContentType: ['application/x-sentry-envelope']. So any event the Overlay receives from the Sidecar with the header Content-Type: application/x-sentry-envelope will be forwarded to the Sentry integration.

processEvent is the function the gets invoked on the integration for every incoming event matching the headers.


An integration can return a function that returns an array of tabs, and also what panel/content Spotlight should render when the tab is selected.

tabs: () => [
id: 'errors',
title: 'Errors',
notificationCount: sentryDataCache.getEvents().filter(e => !e.type).length,
content: ErrorsTab,
id: 'traces',
title: 'Traces',
notificationCount: sentryDataCache.getTraces().length,
content: TracesTab,
id: 'sdks',
title: 'SDKs',
content: SdksTab,

NotificationCount is optional but can determine if Spotlight should update the number on the tab. See IntegrationTab interface for more information.

And that’s already it. This is just a very basic example, you can look at the code directly on Github so see all the details.