Installation

Spotlight can be loaded via a CDN script tag, installed from npm, or self-hosted. Choose the method that fits your stack.

Script Tag (CDN)

The simplest approach. Add a single line to your HTML:

<script
  src="https://spotlight.example.com/sdk/latest/spotlight.min.js"
  data-api-key="sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  defer
></script>

This loads the IIFE build and exposes window.Spotlight globally. The SDK reads the data-api-key attribute and initialises automatically when the DOM is ready.

Output file: spotlight.min.js (~15 KB gzipped)

defer vs async

Use defer rather than async. The SDK needs to read its own script tag attributes at init time, which requires the DOM to be parsed. defer guarantees execution order after parsing.

Pinning a Version

To avoid unexpected changes, pin the SDK to a specific version:

<script
  src="https://spotlight.example.com/sdk/v0.1.0/spotlight.min.js"
  data-api-key="sk_live_xxxx"
  defer
></script>

See SDK versioning for the immutable v{semver} vs rolling latest contract, and why pinned versions never fall back silently on a 404.

npm

Install the package and import it as an ES module:

npm install @spotlight/sdk

Then initialise it in your application code:

ES Module

import Spotlight from '@spotlight/sdk';

await Spotlight.init({
  apiKey: 'sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  tokenSource: 'localStorage',
  tokenKey: 'access_token',
});

TypeScript

import Spotlight from '@spotlight/sdk';

await Spotlight.init({
  apiKey: 'sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  tokenSource: 'localStorage',
  tokenKey: 'access_token',
  debug: process.env.NODE_ENV !== 'production',
});

Package exports:

Export	File	Format
main	dist/spotlight.min.js	IIFE
module	dist/spotlight.esm.js	ES Module

When using a bundler (Vite, webpack, Rollup), the module field is resolved automatically so you get tree-shakeable ESM.

Framework Examples

React

// src/spotlight.js
import Spotlight from '@spotlight/sdk';

let initialized = false;

export async function initSpotlight() {
  if (initialized) return;
  await Spotlight.init({
    apiKey: import.meta.env.VITE_SPOTLIGHT_API_KEY,
    tokenSource: 'localStorage',
    tokenKey: 'auth_token',
  });
  initialized = true;
}

// In your App.jsx or layout component:
import { useEffect } from 'react';
import { initSpotlight } from './spotlight';

function App() {
  useEffect(() => {
    initSpotlight();
    return () => Spotlight.destroy();
  }, []);

  return <div>{/* your app */}</div>;
}

Vue 3

<!-- src/plugins/spotlight.js -->
<script>
import Spotlight from '@spotlight/sdk';

export default {
  install(app) {
    Spotlight.init({
      apiKey: import.meta.env.VITE_SPOTLIGHT_API_KEY,
      tokenSource: 'localStorage',
      tokenKey: 'auth_token',
    });

    app.config.globalProperties.$spotlight = Spotlight;
  },
};
</script>

Angular

// src/app/spotlight.service.ts
import { Injectable, OnDestroy } from '@angular/core';
import Spotlight from '@spotlight/sdk';

@Injectable({ providedIn: 'root' })
export class SpotlightService implements OnDestroy {
  private initialized = false;

  async init(apiKey: string): Promise<void> {
    if (this.initialized) return;
    await Spotlight.init({
      apiKey,
      tokenSource: 'localStorage',
      tokenKey: 'auth_token',
    });
    this.initialized = true;
  }

  ngOnDestroy(): void {
    Spotlight.destroy();
  }
}

Self-Hosted

If you run your own Spotlight backend, build the SDK from source and serve it from your own CDN or static assets.

Build from Source

git clone https://github.com/your-org/spotlight.git
cd spotlight/frontend-sdk
npm install
npm run build

This produces two files in dist/:

dist/
  spotlight.min.js    # IIFE build (for script tags)
  spotlight.esm.js    # ES module build (for bundlers)

Serve the SDK

Copy dist/spotlight.min.js to your static asset server or CDN bucket. Then reference it with a custom baseUrl pointing to your own API:

<script
  src="https://spotlight.yourcompany.com/sdk/latest/spotlight.min.js"
  defer
></script>
<script>
  Spotlight.init({
    apiKey: 'sk_live_xxxx',
    baseUrl: 'https://spotlight.yourcompany.com/api',
  });
</script>

baseUrl must not have a trailing slash

The SDK strips trailing slashes automatically, but for clarity, omit them in configuration: https://spotlight.yourcompany.com/api not https://spotlight.yourcompany.com/api/.

Infrastructure

The self-hosted backend requires:

Component	Service
API	AWS Lambda + API Gateway (Python 3.13, FastAPI)
Database	DynamoDB (pay-per-request billing)
Events	EventBridge + DynamoDB Streams
CDN	CloudFront + S3 (for SDK assets)

See the Architecture guide for the full infrastructure breakdown and Terraform modules.