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
- Every check is synchronous. No promise, no request per check. About 60ns; a percentage rollout about 0.5µs.
- It keeps answering when featurekit is gone. Last good snapshot in memory, then the one on disk, then your default.
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
| Mode | What it does |
|---|---|
streaming (default) | Server-sent events. Falls back to polling when the server sheds connections. |
polling | Asks every pollIntervalMs (30 seconds by default). A poll that's already current costs a 304 and no body. |
offline | Never 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.