Install

npm install noibu-feature-flag

Quick start

Set up the context, wait for the provider to be ready, then evaluate flags.

import { NoibuFeatureFlag, NoibuFeatureFlagProvider } from "noibu-feature-flag";

const provider = new NoibuFeatureFlagProvider({ apiKey: "your-api-key" });

// 1. Describe the visitor. Optional — see "Identifying visitors" below.
await NoibuFeatureFlag.setContext({ targetingKey: "your-user-id" });

// 2. Register the provider and wait for the first flags to load.
// setProviderAndWait rejects if the provider fails to initialize (e.g. the
// network request failed) — reads still fall back to defaults, but the
// await itself can throw, so catch it if a flaky network shouldn't block startup.
try {
  await NoibuFeatureFlag.setProviderAndWait(provider);
} catch {
  // Provider failed to initialize; flag reads below will return their defaults.
}

// 3. Evaluate.
const client = NoibuFeatureFlag.getClient();

if (client.getBooleanValue("checkout-redesign", false)) {
  // ...
}

Reading flags

Every read takes a default value, returned whenever the flag can't be resolved — before the provider is ready, if the flag doesn't exist, or if the network call failed. Reads are synchronous and never throw.

client.getBooleanValue("checkout-redesign", false);
client.getStringValue("add-to-cart-button-position", "default_button");
client.getNumberValue("free-shipping-threshold", 50);
client.getObjectValue("promo-banner", { enabled: false });

The ...Details variants return the variation name and the reason alongside the value:

const { value, variant, reason } = client.getStringDetails(
  "add-to-cart-button-position",
  "default_button"
);

If you'd rather not await the provider, register it and read flags once it's ready:

import { NoibuProviderEvents } from "noibu-feature-flag";

NoibuFeatureFlag.setProvider(provider);

client.addHandler(NoibuProviderEvents.Ready, () => {
  console.log(client.getStringValue("add-to-cart-button-position", "default_button"));
});

NoibuProviderEvents also carries ConfigurationChanged (flags were updated server-side), ContextChanged, Error and Stale.

Options

apiKey is the only required option.

| Option | Default | Description | | --- | --- | --- | | apiKey | — | Your Noibu feature flag API key. | | targetingKey | minted automatically | The id flags are evaluated against — see below. |

Identifying visitors

Flags are evaluated against a targeting key, which decides which variation a visitor gets. You don't have to supply one: the SDK mints a stable id, stores it in the browser, and reuses it on later visits so a visitor stays in the same variation.

To bucket on your own identifier instead — a user id, account id, anything stable — set it on the context, along with any custom attributes your targeting rules use:

await NoibuFeatureFlag.setContext({
  targetingKey: "your-user-id"
});

Any non-empty string works; it doesn't have to be a UUID.

If you already know the key before building the provider, pass it as an option instead — then the SDK stores no id of its own. A targetingKey on the context still takes precedence.

const provider = new NoibuFeatureFlagProvider({
  apiKey: "your-api-key",
  targetingKey: "your-user-id",
});

Calling setContext again after the provider is ready re-fetches flags for the new context — for example once a visitor logs in.