Quickstart
One command detects your framework, wires the SDK, verifies events arrive, and prints your first live ribbon. Budget about 90 seconds.
Get a write key
Create a workspace (beta, invite-gated) and copy the write key from Settings → Keys. Write keys are client-safe by design: they can submit events and read nothing.
Run the wizard in your project
npx sonder-init snd_pk_your_write_key
It detects Next.js, Vite + React, plain React, or plain HTML; injects the
provider or init file; writes .sonder/config.json (masking rules,
sample rate); sends a verification batch to the collector; and prints the ribbon
it captured, so you see the masking working before any real traffic:
Sonder detected vite-react in your-app
Sonder wrote .sonder/config.json and touched src/sonder.ts, src/main.tsx
Session: wizard-1751551200000
Live ribbon:
click "Save changes for [masked]" (button) x2
dead_click "Save changes" (button) x1
Board: https://app.sonder.so/issuesDeploy and watch the board
That's the whole install. Real sessions start filling the board; the health page confirms your semantic events are flowing (and alerts if they ever silently stop). The engine's first watch run groups friction into tracked issues; diagnosis follows on the weekly cadence.
Manual install
If you'd rather make the edits yourself:
npm install @sonderhq/sdk// src/sonder.ts — created for you by `npx sonder-init`
import { initSonder } from "@sonderhq/sdk";
export const sonder = initSonder({
writeKey: "snd_pk_your_write_key",
buildId: import.meta.env.VITE_SONDER_BUILD_ID ?? import.meta.env.MODE
});
Import that module once, first thing in your entry file (src/main.tsx
or equivalent). Framework-specific setups: React ·
Next.js ·
plain JavaScript.
What happens next
- Autocapture is on. Clicks, inputs (values always masked), submits, and SPA navigations are recorded by meaning. No custom events required.
- Friction is derived at the edge. Rage clicks and dead clicks ship with a probe of what was on screen.
- Set
buildIdper deploy. It's how fixes get confirmed and regressions get caught. See the API reference.