Install on Web

The Sankofa Web SDK ships as seven independent packages on npm (each at version 0.1.2) so you only pay for what you use. The core is @sankofa/browser; every other product (Catch, Switch, Config, Pulse, Replay-rrweb, React) is an optional plugin package.

This guide installs the core package. To add error tracking, feature flags, surveys, replay, or React hooks, install the matching package after this and follow the linked package guide.

1. Install the package

npm install @sankofa/browser

pnpm add @sankofa/browser

yarn add @sankofa/browser

bun add @sankofa/browser

<script src="https://cdn.jsdelivr.net/npm/@sankofa/browser/dist/sankofa.min.js"></script>
<script>
Sankofa.init({
  apiKey: "sk_live_...",
  endpoint: "https://api.sankofa.dev"
});
</script>

The bundled CDN exposes Sankofa as a global — no further setup required. For production we recommend the npm route so your bundler can tree-shake unused modules.

2. Initialize once at app entry

Initialize the SDK exactly once, as early as possible in your app's lifecycle. Subsequent init calls are no-ops, so it's safe to load the module from anywhere.

import { Sankofa } from "@sankofa/browser";

if (typeof window !== "undefined") {
Sankofa.init({
  apiKey: process.env.NEXT_PUBLIC_SANKOFA_KEY!,
  endpoint: "https://api.sankofa.dev",
});
}

import { Sankofa } from "@sankofa/browser";

Sankofa.init({
apiKey: import.meta.env.VITE_SANKOFA_KEY,
endpoint: "https://api.sankofa.dev",
});

import { Sankofa } from "@sankofa/browser";

Sankofa.init({
apiKey: window.ENV.SANKOFA_KEY,
endpoint: "https://api.sankofa.dev",
});

<script src="https://cdn.jsdelivr.net/npm/@sankofa/browser/dist/sankofa.min.js"></script>
<script>
Sankofa.init({ apiKey: "sk_live_...", endpoint: "https://api.sankofa.dev" });
</script>

3. Verify the install

Drop a single track call somewhere reachable — a button click, a route change, or the bottom of your entry file — and reload.

Sankofa.track("install_check", { from: "web-quickstart" });

Open the Sankofa dashboard → your project → Live events. The event should appear within a few seconds, with a web source label. If it's missing, see Troubleshooting.

4. Optional: add product packages

Each Sankofa product is a separate web package. Install only what you need.

What's next