Using Spotlight with Other Frameworks

Spotlight can be utilized in any stack, but in particular is well supported anywhere Sentry integration exists.

There’s a few steps to get started:

1. Install and initialize the Overlay.
2. Run the Sidecar concurrently with your development server.
3. Configure Sentry’s SDKs to send to Spotlight by passing spotlight=True.

1. Installation

Start by installing the @spotlightjs/spotlight package in your existing frontend application.

npm

npm add @spotlightjs/spotlight

pnpm

pnpm add @spotlightjs/spotlight

yarn

yarn add @spotlightjs/spotlight

Note

We’re loading Spotlight with production dependencies as the import is static, but the expectation is that it will be tree-shaken out by checking for a development environment.

If you’re using a dynamic import, its possible you can simply list this in your devDependencies instead.

2. Configuration

Inject the Spotlight overlay into your application:

Dynamic Import

If your bundler supports it, its recommended to do a dynamic import to aid tree-shaking:

if (process.env.NODE_ENV === "development") {
  import('@spotlightjs/spotlight').then((Spotlight) =>
    Spotlight.init({ injectImmediately: true })
  );
}

Vite

import * as Spotlight from '@spotlightjs/spotlight';

// only load Spotlight in dev
if (import.meta.env.DEV) {
  Spotlight.init();
}

Other Bundlers

import * as Spotlight from '@spotlightjs/spotlight';

// only load Spotlight in dev
if (process.env.NODE_ENV === "development") {
  Spotlight.init();
}

Note

It’s important that your check for the dev environment is actually tree-shaken away at production build time. We recommend comparing your build bundle size before and after adding the Spotlight overlay.

Upon loading your UI you should now see the Spotlight toolbar in bottom-right corner of your application.

For more options on how to configure Spotlight’s UI, see Configuration.

Setup Spotlight with Sentry Instructions for Web and Mobile SDKs

3. Run the Sidecar

Spotlight’s architecture requires a sidecar to be running alongside your service. This is to enable streaming data collection from your backend services into the Spotlight overlay.

Vite

Webpack

Other

Bonus: Leverage Sentry SDKs

To get the most value out of Spotlight, configure Sentry’s SDKs. You don’t have to use sentry.io but you can use the them to just power Spotlight.

Web platforms

JavaScript (Browser)

In the Browser you don’t need to set spotlight: true, Spotlight.init() will automatically detect if Sentry is available and if so, hook into the SDK.

Sentry.init({
  dsn: '___DSN___',
});
// In the frontend it's important that you init Spotlight after Sentry
Spotlight.init();

Node

Caution

Requires @sentry/node version 7.82.0 or higher.

Sentry.init({
    dsn: '___DSN___',
    spotlight: process.env.NODE_ENV === "development",
});

Python

Caution

Requires sentry-sdk version 1.37.0 or higher.

sentry_sdk.init(
    dsn="___DSN___",
    # You should only load this in your development environment
    spotlight=bool(os.environ.get("DEV")),
)

PHP

Caution

Requires sentry/sentry version 4.1.0 or higher.

\Sentry\init([
    'dsn' => '___DSN___',
    // You should only load this in your development environment
    'spotlight' => App::environment(['local']),
]);

Ruby

Caution

Requires sentry-ruby version 5.15.0 or higher.

Sentry.init do |config|
    config.dsn = '___DSN___'
    # You should only load this in your development environment
    config.spotlight = Rails.env.development?
end

.NET

Caution

Requires sentry-dotnet version 4.0.0 or higher.

SentrySdk.Init(o =>
{
    o.Dsn = "___DSN___";
#if DEBUG
    // You should only load this in your development environment
    o.EnableSpotlight = true;
#endif
});

Mobile platforms

Android

Caution

Requires sentry-java version 7.4.0 or higher.

SentryAndroid.init(this, options -> {
    options.setDsn("___DSN___");
    // You should only enable this in your development environment
    options.isEnableSpotlight = BuildConfig.DEBUG;
});

You also need to allow cleartext traffic from your emulator to the Sidecar on your host machine by adding the following to src/debug/res/xml/network.xml:

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <!-- Allow cleartext traffic from the emulator to the host machine -->
        <!-- See https://developer.android.com/studio/run/emulator-networking for more details -->
        <domain includeSubdomains="true">10.0.2.2</domain>
    </domain-config>
</network-security-config>

iOS

Caution

Requires sentry-cocoa version 8.21.0 or higher.

SentrySDK.start { options in
    options.dsn = "___DSN___"
#if DEBUG
    // You should only enable this in your development environment
    options.enableSpotlight = true
#endif
}

React Native

Caution

Requires sentry-react-native version 5.18.0 or higher.

Sentry.init({
    dsn: '___DSN___',
    enableSpotlight: __DEV__,
});

Flutter

Caution

Requires sentry-dart version 7.15.0 or higher.

await SentryFlutter.init((options) {
    options.dsn = '___DSN___';
    // You should only enable this in your development environment
    options.spotlight = Spotlight(enabled: kDebugMode);
});