Star
SDKs

Server SDK (Node)

For your backend. It holds the compiled rules in memory, so every check is synchronous, takes any user's context, and never makes a network call.

npm i featurekit-server
import { FeaturekitSDK } from "featurekit-server/sdk";
      
      const flags = new FeaturekitSDK({
        sdkKey: process.env.FEATUREKIT_SDK_KEY,          // fk_srv_…
        baseUrl: "https://flags.internal.acme.com",
        persist: { kind: "file", path: ".featurekit/snapshot.json" },
      });
      
      await flags.ready({ timeoutMs: 5_000 });
      
      if (flags.get("new-checkout", { key: user.id, plan: user.plan }, false)) {
        // synchronous, in memory
      }

Create one instance per process, at startup, and share it. It works in Node, Deno, Bun and edge runtimes: it has no dependencies and uses fetch directly.

Three promises

  1. Every check is synchronous. No promise, no request per check. About 60ns; a percentage rollout about 0.5µs.
  2. It keeps answering when featurekit is gone. Last good snapshot in memory, then the one on disk, then your default.
  3. ready() never rejects. If the timeout passes, it resolves and you serve defaults. A flag service outage shouldn't fail your deploy.

Reading flags

flags.get("new-checkout", ctx, false);              // boolean
      flags.get("promo-banner", ctx, "");                 // string
      flags.get("loyalty-discount", ctx, 0);              // number
      flags.get("theme", ctx, { accent: "#6CF0A6" });     // json
      
      flags.detail("new-checkout", ctx, false);
      // { value: true, variationIndex: 1, reason: { kind: "RULE_MATCH", … } }

The default is required. It's what every call site serves when featurekit is unreachable, the flag doesn't exist, or the value has the wrong type. An optional default would turn into undefined during an outage, and if (undefined) is a wrong answer nobody notices.

Reacting to changes

const off = flags.on("change", ({ flagKey }) => {
        // flagKey is null when a whole snapshot was replaced
      });
      flags.on("state", (state) => log.info({ state }, "featurekit"));   // initializing | connected | reconnecting | offline
      
      off();   // unsubscribe

Modes

ModeWhat it does
streaming (default)Server-sent events. Falls back to polling when the server sheds connections.
pollingAsks every pollIntervalMs (30 seconds by default). A poll that's already current costs a 304 and no body.
offlineNever touches the network. Serves bootstrap and the persisted snapshot. Good for tests and air-gapped builds.

Reconnects use jittered exponential backoff capped at 30 seconds, so a control-plane restart isn't followed by every server reconnecting in the same millisecond. A reconnect sends the version it holds and gets only what changed since.

Persistence and bootstrap

new FeaturekitSDK({
        sdkKey,
        baseUrl,
        bootstrap: snapshotFromRepo,                                     // usable before the first response
        persist: { kind: "file", path: ".featurekit/snapshot.json" },    // survives a restart during an outage
      });

persist also takes any { load(), save() } object, for Redis or S3. A missing or corrupt file counts as "no snapshot yet", never as a reason not to start.

Evaluation summaries

The SDK counts evaluations by flag, variation and reason, and sends one summary every 5 seconds instead of a request per check. It powers the per-flag metrics in the dashboard. Both buffers are capped and drop rather than grow, so analytics can never block a check or leak memory. Turn it off with events: { enabled: false }.

Testing

const flags = new FeaturekitSDK({ sdkKey: "test", mode: "offline", bootstrap: fixtureSnapshot });

Offline mode with a bootstrap snapshot gives you real evaluation with no server.

Shutting down

await flags.close();   // closes the stream, flushes summaries

Every option and method is in the SDK reference.