Web SDK — Voidhash Docs

Install @voidhash/web, allow it in your Content Security Policy and create the client.

The web SDK, @voidhash/web, records page views, product events, sessions and the campaign that brought each visitor to your website or web app, and links visitors to your users. It also evaluates feature flags. A visitor who signs in on your website and in your mobile app is one person in Voidhash.

The web SDK does not present paywalls or make purchases. Web purchases go through Stripe or your own payment provider, and Voidhash records them from there; the SDK supplies the visitor's distinct ID so each purchase lands on the right person. See Sell on the web. Check access on your server, not in the browser, with the server library for Node.js, PHP, Go or Rust, or over HTTP.

To get started, follow the quickstart. Options, methods, events and React bindings are in the Web SDK reference.

Install

@voidhash/web installs from the Voidhash package registry, pkg.voidha.sh. branch:main names the newest build:

npm install @voidhash/web@https://pkg.voidha.sh/@voidhash/web/branch:main effect@^4.0.3

To pin a build, install from https://pkg.voidha.sh/@voidhash/web/<hash>, using the short commit hash at the end of the installed version, such as 83f7412 in 0.0.1-alpha.1-g83f7412.

Alpha

The SDK is an alpha release and isn't on npm yet: npm install @voidhash/web installs an older preview that doesn't match these docs. Builds are kept for three weeks, so pin a recent one and update regularly. See Versions and releases.

Compatibility

Requirement	Version
Browsers	Chrome and Edge 93+, Firefox 92+, Safari 15.4+, on desktop and mobile. The package targets ES2022.
`effect`	Peer dependency `^4.0.3`. An app that already uses `effect` 4 keeps its version.
`react`	Optional peer dependency for `@voidhash/web/react`. React 18 or later.
Frameworks	Any app built with a bundler: Next.js, React Router, TanStack Router, Vue, Svelte and others. Sites without one use the script tag.
Modules	ES modules only, plus a self-contained script-tag build. There is no CommonJS build.

Creating the client and rendering the provider are safe during server rendering. initialize() runs only in the browser; on a server it rejects with an error that says it needs a browser. To send events from your backend, use the Event Capture API or a server library.

Data collection

The SDK sends Voidhash the visitor's anonymous ID, your user ID once you identify them, the pages they view, the events you track, the campaign that brought them, device details and the IP address their events come from. It sets no cookies unless you turn on crossSubdomainIdentity, and keeps its state in localStorage and sessionStorage. Privacy and consent lists every value for your privacy policy and cookie banner.

Content Security Policy

The SDK only makes fetch requests. Allow the origin of baseUrl in connect-src, and the origin of analytics.baseUrl if you set it:

Content-Security-Policy: connect-src 'self' https://api.voidhash.com

With a first-party proxy on your own origin, 'self' covers it; with a tracking domain, allow that domain instead. The npm package loads no scripts, styles, images, fonts or workers and needs no 'unsafe-eval'.

Event batches are sent as text/plain without custom headers, so they need no CORS preflight. Feature flag, identify() and person requests carry x- headers, so the browser sends a preflight OPTIONS request first, which Voidhash answers.

Create the client

Create one client per page and keep it for the page's lifetime. Two clients for the same project each record page views, so every page would be counted twice.

src/lib/voidhash.ts

import { createVoidhashClient } from "@voidhash/web";

export const voidhash = createVoidhashClient({
  publishableKey: "vh_pk_...",
});

void voidhash.initialize();

Use a publishable key; createVoidhashClient refuses a secret key. The key's environment decides where events are recorded: a vh_pk_test_... key records test events, which stay out of production analytics. See API keys.

initialize() loads the SDK's saved state, records the first page view and starts sending events in the background. It never waits for the network. Calls made while it runs wait for it; calls made before you call it reject with VoidhashNotInitializedError. In React, the provider initializes the client. For every option, see Client options.

Bundle size

The SDK adds about 43 kB gzipped to a page that does not otherwise use effect, and the React entry about 1.6 kB more. About 28 kB is the SDK's own code; an app that already uses effect shares the rest. To keep a landing page's first paint fast, initialize the client after your critical content, for example with a dynamic import().

Next steps