This SDK wraps the JavaScript SDK for smoother integration with React applications. However, if you're building a non-React application for web browsers, you should use our JavaScript SDK instead.
@flagsync/react-sdk relies on the React Context API (React 16.3+).
TypeScript is fully supported.
Get your SDK key
To start, you'll first need to locate your SDK key, which is specific to an Environment (e.g. Test, Production, Staging, etc.)
Your API requests are authenticated using SDK keys. Any request that doesn't include an SDK key will return an error.
Client-side SDK keys are safe to expose, and should be used for client-facing applications such as Web Browsers, whereas server-side SDKs can expose details of your flag rules, such as internal email addresses or user keys, and should never be made public.
Install the library
To connect to FlagSync from code, you'll need to install the SDK.
To initialize the FlagSync client, you'll need your SDK key, and core.key, which is often a unique identifier, such as user ID or email, and pass it to FlagSyncProvider.
Similar to other context providers, you can place FlagSyncProvider at the root of your application, or as low in the component tree as you need, assuming your flag retrievals are below that depth.
Flag impression(s) are automatically registered whenever the useFlag or useFlags hook is called from the SDK.
The SDK uses memoization to ensure that renders provoked from outside FlagSync do not result in duplicate impressions.
useFlag
The useFlag hook retrieves the value of a feature flag identified by the flagKey.
This function evaluates the user context against individual targeting rules, percentage rollouts, and default variants to determine and return the appropriate feature flag variant for that specific user.
If the SDK is not ready, either control will be returned, or the defaultValue if one is provided.
The useFlags hook retrieves the values of all feature flags.
This function evaluates the user context against individual targeting rules, percentage rollouts, and default variants to determine and return the appropriate feature flag variants for that specific user.
If the SDK is not ready, either control will be returned, or the defaultValue if one is provided.
The FlagSyncFlag component retrieves the value of a feature flag identified by the flagKey.
This component evaluates the user context against individual targeting rules, percentage rollouts, and default variants to determine and return the appropriate feature flag variant for that specific user.
If the SDK is not ready, either control will be returned, or the defaultValue if one is provided.
The FlagSyncFlags component retrieves the values of all feature flags.
This component evaluates the user context against individual targeting rules, percentage rollouts, and default variants to determine and return the appropriate feature flag variants for that specific user.
If the SDK is not ready, either control will be returned, or the defaultValue if one is provided.
Track user actions or events within the application with the useTrack hook.
Per the type definitions below, if you choose to pass an eventKey to useTrack you are effectively binding the return function that that specific event.
exportconstRegisterButton= () => {const { value } =useFlag<string>('register-button-text','Register');consttrack=useTrack(); // generic track functionconsttrackReg=useTrack('register-event'); // track function for "register-event"useEffect(() => {track('page-load-time',1.234) }, [])return ( <buttononClick={() => {trackReg();// Register the user }} > {value} </button> );};
When you call the track function to submit events, you can optionally provide key-value properties or a numeric eventValue.
For more information on the track function, check out the JavaScript SDK reference.
Flag updates
When a change to a feature flag is made in the FlagSync dashboard, a server-side event (SSE) is sent from FlagSync servers to the SDK.
Value change propagation is on the order of milliseconds.
Unlike the JavaScript SDK, there is no need to listen for events in the React SDK, any component using a useFlag or useFlags hook with re-render automatically, same with <FlagSyncFlag/> and <FlagSyncFlags />.
While the default synchronization method is SSE, you may opt to use polling instead, or disable synchronization entirely. You can control this with sync option
When initializing the config, you can pass custom attributes about the user or user segment, which are automatically made available in the FlagSync Dashboard for individual targeting.
By default, flags are stored in memory, however when running in a Web Browser, you can opt to use LocalStorage instead, which is useful for quickly loading the last state of your flags.
When initializing from LocalStorage, the isReadyFromStore value for useFlag, useFlags, <FlagSyncFlag />, and <FlagSyncFlags /> will be true once the flags have been loaded.
Occurs quickly since no network request is required.
This data may be stale, and should not be considered a replacement for the isReady boolean.
FsConfig
You can configure any of the following option arguments when initializing the config object for <FlagSyncProvider />.
typeFsFlagValue=any;exporttypeFsFlagSet=Record<string,FsFlagValue>;typeCustomAttributeValue=any;typeCustomAttributes=Record<string,CustomAttributeValue>;typeStorageType='memory'|'localstorage';typeSyncType='stream'|'poll'|'off';exportinterfaceFsConfig {/** * The SDK key for the FlagSync project. */readonly sdkKey:string;readonly core: {/** * The unique key for the user, or organization. */ key:string;/** * The custom attributes for the user, or organization, which are * made available for rule targeting in your FlagSync dashboard. * > CustomAttributes: Record<string, CustomAttributeValue> * Example: * { * "email": "user@example.com" * "jobTitle: "QA" * "location": "Boston * } */ attributes?:CustomAttributes; };/** * Initialize the SDK with a set of flags. * > FsFlagSet: Record<string, FsFlagValue>; */readonly bootstrap?:FsFlagSet;/** * The storage configuration for the SDK. * > StorageType: 'memory' | 'localstorage' */readonly storage?: { type?:StorageType; prefix?:string; };/** * The configuration for the SDK's sync mechanism. * > SyncType: 'stream' | 'poll' | 'off'; */readonly sync?: { type?:SyncType; pollRate?:number; };readonly tracking?: { impressions?: { maxQueueSize:number; pushRate:number; }; events?: { maxQueueSize:number; pushRate:number; }; };/** * The configuration for the SDK's logging. * > LogLevel: 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'NONE'; */readonly logLevel?:LogLevel;}