Skip to main content

​
React SDK API reference

Current package: @superflag-sh/react@0.7.0.

​
SuperflagProvider

Important props: Callback failures are contained and reported diagnostically; they do not break evaluation.

​
Value hooks

Each has a *Details counterpart. useFlag and useFlagDetails remain for compatibility. Details include value, variation, reason, source, config version, matched rules and segments, prerequisite results, and stable errors.

​
State and client hooks

useFlags() exposes:
  • status: idle | loading | refreshing | ready | stale | error | rate-limited;
  • source: cache | network | default;
  • app/environment identity and config version;
  • fetch time, age, stale state, and bounded error; and
  • a coalesced refresh().
In 0.7, this is an explicit public result Interface rather than a spread of the provider’s private context object. Untyped consumers that reached undocumented context fields must migrate to the listed state or useSuperflagClient(). useSuperflagClient() returns imperative getFlag, getFlagDetails, track, flush, shutdown, and refresh methods. createTypedHooks<ValueMap>() binds flag keys to value types.

​
Cache contract

The SDK serves a validated, identity-bound cache within the hard stale limit, then revalidates with an opaque authorization-scoped ETag. A valid 304 renews freshness. Authentication failure, app/environment identity mismatch, invalid schema, or config-version rollback cannot keep serving the rejected state. The shared @superflag-sh/core/cache Module partitions entries by normalized endpoint and a SHA-256 client-key fingerprint, then binds them to app and environment. This React Adapter owns local-storage/session-memory persistence and browser lifecycle. Raw keys are never persisted.

​
Telemetry contract

Hosted telemetry posts bounded versioned batches to /api/v1/events/batch. Queue, retry, backpressure, exposure deduplication, and shutdown are bounded and fail open. track(flagKey, metricKey, value?) requires a current identity and a prior real exposure. Omitting value records a binary conversion; a provided value must be finite.