Get Started

Pull down the repo (or your fork):

git clone https://github.com/getsentry/spotlight.git

Spotlight relies on a pnpm monorepo. You’ll need to install pnpm to get things going, which can be done with Volta.

Ensure the node and pnpm are available:

volta install node pnpm

Install the package requirements:

pnpm install

And finally, run an initial build:

pnpm build

Development

Depending on what you’re doing there’s two paths to develop against the overlay.

Against the example “Playground” application

If you simply want to run Spotlight against the example application, you can spin that up using:

pnpm dev:playground

With existing data

If you just want to test things out with some example traces and errors you can spin up the Spotlight repo into watch mode:

pnpm dev

Then head over to packages/overlay/_fixtures and run:

./send_to_sidecar.cjs

This will send all the sample data to Spotlight. You can also pick a specific file and pass that as an argument to the script instead:

./send_to_sidecar.cjs envelope_php_error.txt

Linking against an existing project

Additionally you may want to link it into an existing project. This is a little brittle, and we’re not experts here, so your mileage may vary.

First, when in the Spotlight root directory, you’ll need to link the packages you’re referencing (likely @spotlightjs/spotlight):

pnpm link --global -C packages/spotlight

You can now link these within your project. For example if you’re using pnpm:

pnpm link --global @spotlightjs/spotlight

Repository Structure

The monorepo is mostly straight forward, but here’s a quick summary:

spotlight
└── packages
    ├── overlay      // @spotlightjs/overlay   - the main overlay
    ├── sidecar      // @spotlightjs/sidecar   - the sidecar (proxy) for streaming data
    ├── spotlight    // @spotlightjs/spotlight - the main spotlight package, combining overlay and sidecar
    ├── tsconfig     // @spotlightjs/tsconfig  - shared tsconfig
    └── website      // @spotlightjs/website   - the main overlay