LiftCanary

SDKs

JavaScript (npm)

@liftcanary/js for single-page apps and frameworks.

@liftcanary/js is the browser SDK as an npm package, for apps built with React, Vue, Svelte, Next.js and similar. It decides flags and tracks events like the snippet, but leaves page-level features (redirect tests, auto-tracked goals, location triggers, automatic attributes) to you or to the snippet, which can run alongside it.

Install#

Terminal
npm install @liftcanary/js

Quick start#

TypeScript
import { createClient, getAnonymousId } from "@liftcanary/js";

export const liftcanary = createClient({ sdkKey: "pk_..." });

await liftcanary.ready(); // waits for the first datafile, 3 s at most
const user = liftcanary.createUser({
  id: currentUser?.id ?? getAnonymousId(),
  attributes: { country: "TR", plan: currentUser?.plan ?? "free" },
});

if (user.isEnabled("new_checkout")) showOnePageCheckout();
const label = user.getVariable("new_checkout", "button_text", "Buy now");
user.track("purchase", { value: 499.9, properties: { currency: "TRY" } });

Login and bucketing#

Switching from the anonymous id to the user id at login can change a variation. For tests that start before login, keep the anonymous id as the bucketing id: createUser({ id: user.id, bucketingId: getAnonymousId() }). See which id decides the variation.

What the browser client adds#

  • Starts downloading the datafile as soon as it's created, and refreshes it when the tab becomes visible again.
  • Keeps queued events in localStorage so a reload doesn't lose them, and sends them with sendBeacon when the page is hidden or closed.
  • Saves the last datafile in localStorage; if a later download fails or is too slow, decisions use it instead of defaults (cacheDatafile: false turns this off).
  • getAnonymousId() returns a stable id stored in localStorage (in memory when storage is blocked, e.g. some private modes).

Options (in addition to the shared client options)

persistEvents
boolean
Default true. Pass false to use no localStorage at all: events stay in memory and the datafile isn't cached. For example before cookie consent.

Every other option (cdnUrl, eventsUrl, pollingIntervalMs, datafile…) is shared by all SDKs: see Client options.

React#

The React hooks ship with the React Native package today. In a web React app, a small hook over the client is enough:

use-flag.ts
import { useMemo, useSyncExternalStore } from "react";
import { liftcanary } from "./liftcanary";

const subscribe = (cb: () => void) => liftcanary.subscribe(cb);
const revision = () => liftcanary.revision;

export function useDecision(user: { id: string; attributes?: Record<string, string | number | boolean> }, flagKey: string) {
  const rev = useSyncExternalStore(subscribe, revision, revision); // re-render on new datafiles
  return useMemo(() => liftcanary.createUser(user).decide(flagKey), [user, flagKey, rev]);
}

Server rendering#

To render the right variation on the server and avoid a flash on the client, decide with the Node.js SDK during rendering and pass the same datafile to the browser client, so its first decisions need no network request:

TypeScript
// Server: embed the datafile the page was rendered with
const datafile = serverClient.datafile;

// Browser
const liftcanary = createClient({ sdkKey: "pk_...", datafile });

Decisions need no storage. With persistEvents: false the client writes nothing to localStorage; pair it with an id you keep in memory instead of getAnonymousId(), which stores one. Events are still sent to the collector, so if nothing may be sent before consent, don't call track or decide experiment flags until the visitor agrees.