@spectra-js/react

React bindings for Spectra tracker. This package wraps the browser tracker in a provider, exposes React context for init status, and offers small helpers for imperative access.

Install

npm install @spectra-js/react

React 18 or 19 is required (peerDependencies).

Quick start

Wrap your app (or a subtree) with SpectraProvider and pass your Spectra accountId. Optionally set apiKey, debug, or a custom endpoint.

import { SpectraProvider } from "@spectra-js/react";

export function App() {
  return (
    <SpectraProvider
      accountId="your-account-id"
      apiKey={import.meta.env.VITE_SPECTRA_API_KEY}
      onReady={(spectra) => spectra.logEvent("spectra_ready")}
      onError={(err) => console.error(err)}
    >
      <YourApp />
    </SpectraProvider>
  );
}

Spectra is the same component as SpectraProvider but without a children slot in the type—it is useful when you only need side effects (init + callbacks) and render nothing extra.

useSpectra

Inside any descendant of SpectraProvider, read initialization state and the live Spectra instance:

import { useSpectra } from "@spectra-js/react";

function Status() {
  const { status, spectra, error } = useSpectra();

  if (status === "loading") return <p>Loading analytics…</p>;
  if (status === "error") return <p>{error?.message}</p>;
  if (status === "ready" && spectra) {
    // use spectra APIs from @spectra-js/tracker
    spectra.logEvent("my_event");
  }
  return null;
}

status is one of "idle" | "loading" | "ready" | "error". On the server, the provider starts in "idle" with spectra: null until a browser client hydrates and runs the init effect.

Imperative helpers

For code outside React trees (or after you know Spectra is ready):

• ensureSpectra(options) — Returns a promise that resolves to the Spectra instance. Rejects outside a browser (window / document unavailable). If Spectra was already initialized, the first configuration wins; later calls with different options are ignored and a warning is logged.
• getSpectra() — Returns the current instance or null if not ready.
• isSpectraInitialized() — Whether init has completed at least once in this JS realm.

Options match the tracker’s config (EnsureSpectraOptions / SpectraInitConfig from @spectra-js/tracker).

TypeScript

The package exports types such as SpectraProviderProps, SpectraContextValue, SpectraStatus, SpectraInitConfig, SpectraGlobal, SpectraEventPayload, and EnsureSpectraOptions.

License

MIT