@clearlaunch/flags

Feature flags for the browser, controlled from ClearLaunch. No dependencies.

npm install @clearlaunch/flags

import { clearFlags } from '@clearlaunch/flags';

const flags = clearFlags({
  projectKey: 'your-flag-project-key',   // ClearLaunch -> project -> Feature Flags
  environment: 'production',
  fallbacks: { 'new-checkout': false },  // used before load, and if we're unreachable
});

await flags.load({ id: user.id, plan: user.plan });

if (flags.isOn('new-checkout')) showNewCheckout();
const limit = flags.get('max-items', 10);

Failure is a first-class case

load() never throws and never leaves a read undefined. Reads fall back to the caller's argument, then fallbacks, then false. A flag service that can take down the app it gates is worse than no flag service.

ready tells you whether you have live values or fallbacks. A failed refresh keeps the last known-good values rather than reverting a running app.

API

| | | |---|---| | load(user?) | Fetch values. Call once at startup. | | identify(user) | Re-evaluate as a different user. | | refresh() | Re-fetch for the current user. | | isOn(key, fallback?) | Boolean read. | | get(key, fallback) | Typed read for string/number flags. | | detail(key) | Value plus reason and ruleId. | | all() | Every current value. | | subscribe(fn) | Called on every change. Returns an unsubscribe. | | ready | true once a load has succeeded. | | configVersion | Changes only when the flag config changes. |

Pass a stable id

Rollout percentage buckets on user.id, so the same user stays on the same side of a 20% rollout. Without it, a user can flip between page loads.

Values, not rules

This SDK receives evaluated values only — never your targeting rules. Rules name specific customers and unreleased work, and anything shipped to a browser is public. Use the server-side SDK when you need local evaluation with rules.

Auto-discovery

Keys you read are reported to ClearLaunch, so a flag used in code but never configured shows up as a draft rather than existing only in the source. A draft is never evaluated — it is there for you to see and decide on. Disable with reportKnownKeys: false.