Core Concepts

Feature Flags

Control feature rollouts with boolean, string, number, and JSON flags. Evaluate locally for sub-ms performance or server-side for real-time accuracy.

Flag Types

Type	Example Value	Use Case
boolean	`true`	Simple on/off toggles
string	`"variant-b"`	A/B test variants, theme names
number	`25`	Limits, thresholds, quantities
json	`{"color":"#0f0"}`	Complex configuration objects

Local Evaluation

By default, the SDK evaluates flags locally in-memory from the cached configuration payload. This gives you sub-millisecond response times with zero network calls.

Boolean Flags

typescript

// Simple boolean check
if (client.getFlag("dark-mode", { userId: "user_123" })) {
  enableDarkMode();
}

// With default value (returns false if flag not found)
const enabled = client.getFlag("new-feature", context, false);

Typed Flag Values

typescript

// String value
const color = client.getFlagValue<string>("button-color", context, "#000");

// Number value
const maxItems = client.getFlagValue<number>("max-cart-items", context, 10);

// JSON value
const config = client.getFlagValue<{ limit: number; enabled: boolean }>(
  "checkout-config", context, { limit: 5, enabled: false }
);

Full Evaluation Result

Get the complete evaluation result including the reason why a particular value was returned.

typescript

const result = client.evaluateFlag("dark-mode", context);

console.log(result.key);          // "dark-mode"
console.log(result.enabled);      // true
console.log(result.value);        // true
console.log(result.reason);       // "TARGETING_MATCH"
console.log(result.variationKey); // "variation-a" or null

// Evaluate all flags at once
const allFlags = client.evaluateAllFlags(context);

Server-Side Evaluation

For absolute real-time accuracy, call the backend directly. This makes a network request to POST /sdk/evaluate and returns the freshest result.

typescript

// Single flag (network call)
const result = await client.evaluateFlagRemote("dark-mode", context);

// All flags at once (single network call)
const allResults = await client.evaluateAllFlagsRemote(context);

Targeting Rules

Targeting rules let you serve different flag values to different users based on their attributes. Rules are evaluated in priority order on the backend and cached in the SDK payload.

Supported Operators

neq

gte

lte

not_in

contains

not_contains

starts_with

ends_with

regex

exists

Evaluation Context

Pass user attributes to enable targeting. The SDK merges per-call context with the default context (per-call takes precedence).

typescript

const context = {
  userId: "user_123",        // Used for overrides & rollout bucketing
  attributes: {
    plan: "premium",         // String matching
    country: "US",           // Geo targeting
    app_version: "2.5.0",    // Version gates
    beta_tester: true,       // Boolean flags
    signup_date: "2025-01-15" // Date comparisons
  },
};

Evaluation Order

The SDK evaluates flags in this exact order, matching the backend logic:

OFF

Flag is globally disabled → returns default value

KILLED

Kill switch is active → returns default, overriding all rules

OVERRIDE

User has a pinned override → returns the override value

TARGETING_MATCH

A targeting rule matched → returns the rule's variation

ROLLOUT

User falls outside rollout percentage → returns default

DEFAULT

Flag is enabled, no rules matched → returns the flag's value

Percentage Rollouts

Gradually roll out features to a percentage of users. The SDK uses consistent hashing (djb2) to ensure the same user always gets the same result — no flickering between sessions.

Authentication Remote Config