Browser SDK

StatsKitClient runs in the browser (and any public/mobile context). The server pre-evaluates your flags and returns a sanitized payload, resolved values only, no targeting rules cross the wire, so the key is safe to ship in your bundle.

Browser-safe key

Use a public key: csk_live_… (a dedicated SDK client key) or vpk_live_…. Never put a secret key (ssk_/vsk_) in browser code, the browser client throws if you do.

Install

npm install @statskit/sdk

Initialize

Create the client with your context and await init(). The last payload is cached in localStorage, so a returning visitor evaluates flags on the very first line, before any network request completes.

flags.ts

import { StatsKitClient } from "@statskit/sdk";

export const statskit = await new StatsKitClient({
  clientKey: "csk_live_xxx", // public key, safe in the browser
  context: { key: user.id, attributes: { plan: user.plan, country: user.country } },
}).init();

Fresh config is fetched in the background and polled every 60s. To update instantly on publish, enable the SSE stream, see Server SDK → updates (the same options apply).

Evaluate

Pass the flag key and a default. Evaluation never throws, a missing flag or a network outage returns your default.

boolean

if (statskit.boolVariation("new-checkout", false)) {
  // show the new checkout
}

string

const theme = statskit.stringVariation("banner-theme", "default");

number

const limit = statskit.numberVariation("upload-limit", 5);

json

const config = statskit.jsonVariation("home-layout", { hero: "a" });

typed / all

// Generic typed read
const cohort = statskit.variation<string>("cohort", "control");

// Every flag at once
const all = statskit.allFlags();

// Value + reason + config version
const { value, reason, version } = statskit.detail("new-checkout", false);

Context and attributes

The browser client holds one identity at a time: set it once, and every variation() uses it. There’s no per-call context argument.

The context is { key, attributes }: key is the stable bucketing unit (deterministic assignment), and attributes are what the server’s targeting rules reference.

Re-target after login or when an attribute changes with identify(). This re-fetches flags for the new identity (and re-renders the React hooks):

await statskit.identify({ key: user.id, attributes: { plan: "premium", country: "US" } });

statskit.boolVariation("new-checkout", false); // uses the current context
statskit.getContext();                         // read it back

Note

A key-only context uses the CDN-cached GET /v1/client-config. Adding attributes switches to an uncacheable POST, same result, slightly less cacheable.

Exposures

Every variation() call records an exposure (which context saw which variation) and batches it to StatsKit for experiment analytics. Only the context key is sent, the server hashes it, and attributes are never included. Disable with:

new StatsKitClient({ clientKey: "csk_live_xxx", sendExposures: false });

Full example

checkout.ts

import { StatsKitClient } from "@statskit/sdk";

const statskit = await new StatsKitClient({
  clientKey: "csk_live_xxx",
  context: { key: currentUser.id, attributes: { plan: currentUser.plan } },
  plugins: [
    { name: "logger", onEvaluation: (d) => console.log(d.flagKey, "→", d.value) },
  ],
}).init();

function renderCheckout() {
  if (statskit.boolVariation("new-checkout", false)) {
    return new NewCheckout();
  }
  return new OldCheckout();
}

// on login
async function onLogin(user) {
  await statskit.identify({ key: user.id, attributes: { plan: user.plan } });
  renderCheckout();
}

Using React? See React binding. For the full options table and error handling, see the SDK overview.