@dads-framework/client-feature-flags
On this page
Feature state in the browser: a runtime that keeps each context's flags and hash apart, and React hooks that read it. The application supplies the loader and reports response hashes from its own transport.
Try it
In a React 19 TypeScript app, install the client and the shared state schema.
npm install @dads-framework/client-feature-flags @dads-framework/feature-flags react@^19
Render <ExportAvailability tenantId="north" /> from your app. The sample loader
gives one tenant the export flag and returns an empty list for other tenants.
import {
FeatureStateRuntime,
useActivateFeatureState,
useFeatureEnabled,
} from "@dads-framework/client-feature-flags";
import { effectiveFeatureStateSchema } from "@dads-framework/feature-flags/contract";
const exportFeature = "billing.invoices.bulk-export";
const runtime = new FeatureStateRuntime(async (tenantId) =>
effectiveFeatureStateSchema.parse({
features: tenantId === "north" ? [exportFeature] : [],
stateHash: tenantId === "north" ? "north-v1" : "other-v1",
}),
);
export function ExportAvailability({ tenantId }: { tenantId: string }) {
useActivateFeatureState(runtime, tenantId);
const enabled = useFeatureEnabled(runtime, tenantId, exportFeature);
return <p>{enabled ? "Bulk export available" : "Bulk export unavailable"}</p>;
}
After the loader resolves, north shows Bulk export available. Switch the
prop to south to see Bulk export unavailable. In the app, read the
effective state from your authorized feature-state endpoint and enforce the
flag and permission on the export endpoint.
The runtime tests use a loader with two tenants to check that their feature lists and state hashes stay separate.
Use it
new FeatureStateRuntime(load):activate(contextKey),hydrate,snapshot,isEnabled,subscribe,refreshActiveContext.observeResponse({ contextKey, stateHash }): call it with thex-feature-state-hashof each response; a new hash refreshes that context once.hashFor(contextKey): send it asx-client-feature-state-hashso the server can refuse a write made against stale flags.useActivateFeatureState,useFeatureState,useFeatureEnabled: the React side, throughuseSyncExternalStore.
What it refuses to do
- It never reads a context as on before its flags load: unhydrated means off.
- It never turns flags off because a refresh failed. It keeps the last known
ones and sets
refreshFailed. - It never mixes contexts. Each context key has its own flags and hash.
- It is a display gate. The server's own check is the wall.
Contract
| Shape | Fields |
|---|---|
FeatureStateSnapshot |
contextKey, features, stateHash, hydrated, refreshFailed |
FeatureStateLoader |
(contextKey) => Promise<EffectiveFeatureState> |