Evaluate your first flag with sdk-js

This walks through the smallest working setup for @rollfuse/sdk-js in a Node.js service: install the package, construct a client, start it, and read a flag's value with evaluate().

Install the package

npm install @rollfuse/sdk-js

Construct and start the client

RollfuseClient requires two options: baseUrl and credential. The credential is a bearer token issued for a Service Credential scoped to one environment.

import { RollfuseClient } from "@rollfuse/sdk-js";

const client = new RollfuseClient({
  baseUrl: "https://api.rollfuse.com",
  credential: process.env.ROLLFUSE_CREDENTIAL!, // set before running
});

await client.start();

start() begins polling GET /v1/config in the background and resolves once the first Configuration has been fetched. If your service would rather not block startup on that network round trip, call start() without awaiting it and rely on evaluate()'s fallback option in the meantime.

Evaluate a flag

Once a Configuration is cached, evaluate() reads it synchronously: no network call happens on this path.

const subjectKey = "user-42";

const result = client.evaluate(subjectKey, "checkout-redesign", {
  attributes: { plan: "pro" },
  fallback: false,
});

if (result.value === true) {
  // serve the new checkout flow
} else {
  // serve the existing checkout flow
}

result carries the resolved value, the reason the evaluation landed there, and the variation_key that was selected. If no Configuration has loaded yet and no fallback was supplied, evaluate() throws ConfigNotReadyError. If the flag key does not exist in the Configuration and no fallback was supplied, it throws FlagNotFoundError. Supplying fallback turns both cases into a safe default instead of an exception.

Evaluate every flag at once

evaluateAll() runs the same synchronous evaluation for every flag in the cached Configuration, for one subject:

const results = client.evaluateAll(subjectKey, {
  attributes: { plan: "pro" },
});

console.log(results.find((r) => r.flag_key === "checkout-redesign")?.value);

evaluateAll() returns an array of EvaluationResult, one per flag in the Configuration, not an object keyed by flag key. Find the one you want by its flag_key.

This is the same call a server-rendered page uses to hand a full set of EvaluationResults to @rollfuse/sdk-react's RollfuseProvider.

Shut down cleanly

await client.close();

close() stops polling, flushes any exposure events still queued, and releases open connections. Use stop() instead if you want polling and flushing to end immediately without submitting what is queued, for example inside a test.

With a client started and a first flag evaluated, the next step is deciding which credential to run this against in each environment: see Issue and revoke environment credentials.