SDK Documentation

Installation

Install the SDK from npm. One package covers both browser and Node.js environments.

npm install @flaggy.io/sdk-js

Quick Start

Three steps to evaluate your first flag.

import { flaggy } from "@flaggy.io/sdk-js";

export const flagClient = flaggy({
  apiKey: process.env.FLAGGY_API_KEY!,
});

await flagClient.initialize();

if (flagClient.isEnabled("new-checkout", { key: "user-123" })) {
  // show new checkout
}

Setup by Environment

React / Browser

// src/lib/flaggy.ts
import { flaggy } from "@flaggy.io/sdk-js";

export const flagClient = flaggy({
  apiKey: import.meta.env.VITE_FLAGGY_API_KEY!,
  environment: import.meta.env.VITE_ENVIRONMENT,
});

// src/main.tsx
await flagClient.initialize();

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <App />
  </StrictMode>,
);

if (flagClient.isEnabled("new-header", { key: user.id, plan: user.plan })) {
  return <NewHeader />;
}

Node.js

// src/lib/flaggy.ts
import { flaggy } from "@flaggy.io/sdk-js";

export const flagClient = flaggy({
  apiKey: process.env.FLAGGY_API_KEY!,
  environment: process.env.NODE_ENV,
});

// src/server.ts
await flagClient.initialize();

app.listen(3000);

if (flagClient.isEnabled("new-algorithm", { key: req.user.id, plan: req.user.plan })) {
  // use new algorithm
}

Configuration

Options passed to flaggy() when creating the client.

const flagClient = flaggy({
  apiKey: "your-api-key",     // required
  environment: "production",  // optional — defaults to "production"
  onError: (err) => {         // optional — called on fetch failure
    console.warn(err);
  },
});

Initialization

Call client.initialize() once at application startup before evaluating any flags.

Checking Flags

isEnabled evaluates a flag and returns a boolean. Evaluation is local — no network call happens at the point of evaluation.

// Basic on/off flag
client.isEnabled("my-flag");

// With context for targeting
client.isEnabled("my-flag", { key: "user-123", plan: "pro" });

// With a custom default
client.isEnabled("my-flag", { key: "user-123" }, false);

If the flag doesn't exist, isEnabled returns defaultValue (default: false). Flags with no segments return true when enabled — they are global on/off switches.

Context Object

The context is a flat key-value object describing the entity being evaluated. It determines which segments the entity belongs to.

flagClient.isEnabled("new-dashboard", {
  key: "user-123",   // required — stable entity identifier
  plan: "pro",
  country: "US",
  betaOptIn: true,
});

flagClient.isEnabled("enterprise-feature", {
  key: "acme-corp",
  plan: "enterprise",
  company_size: 500,
});

flagClient.isEnabled("new-onboarding", {
  key: "device-abc123",
  platform: "ios",
  app_version: "2.1.0",
});

All attribute values are coerced to strings before comparison. If an attribute is missing from the context, conditions that reference it evaluate to false.

Segment Targeting

Segments let you enable a flag only for entities that match specific attributes. Each segment has a rollout percentage and a set of conditions.

• All conditions within a segment must match — AND logic. e.g. plan equals "pro" AND country equals "US"
• Segments are evaluated in priority order — the first matching segment wins.
• Rollout percentage is deterministic — the same entity always gets the same result (bucketed via MurmurHash3 on the key).

Condition operators

Evaluation Logic

When you call isEnabled, the SDK evaluates the flag in this order:

Analytics

The SDK automatically records flag evaluations and flushes them to Flaggy in the background. No configuration required.

Event shape

{
  "flag_key": "new-feature",
  "result": true,
  "segment_matched": "beta-users",
  "context_key": "user-123"   // hashed before storage
}

segment_matched is the key of the matching segment, or "no_match" if none matched. context_key is your entity key, hashed before storage.

Caching & Refresh

The SDK caches flags locally and refreshes them automatically in the background.

API Reference

client.isEnabled(flagName: string, context?: object, defaultValue?: boolean): boolean

const flags = client.getAllFlags();
// Returns: Record<string, FeatureFlag> — shallow copy of the cache