Overview
The@flagsync/react-sdk
integrates into React applications for client-side feature management and event tracking—ideal for single-user contexts like browser environments.
Requires React 16.3+ due to its dependency on the React Context API.
Installation
Install the SDK with your preferred package manager:Quickstart
A basic example of using the SDK in a React application:Initialization
Get Your SDK Key
Find your client-side SDK key in your workspace settings—safe for web/mobile apps (keep server-side keys private).Initialize the SDK
Wrap your application withFlagSyncProvider
and provide the required configuration:
Ensure the
key
in FsUserContext
is unique and persistent for accurate MAU tracking and consistent flag evaluations. See User Context Best Practices for details.Wait for Readiness
Prevent flickering by ensuring the SDK is ready before your app renders. Use thewaitForReady
prop in FlagSyncProvider
to delay rendering until the SDK is initialized, or check readiness manually with hooks or render prop components:
1
Using waitForReady
Add
waitForReady
to FlagSyncProvider
to delay rendering until the SDK is ready, avoiding flicker during initialization.2
Using hooks or render prop components
Check isReady with hooks like
useFlag
, useFlags
, or useFlagSyncClient
to control renderingIdentical properties are provided in
<FlagSyncFlag />
, and <FlagSyncFlags />
.SDK Not Ready
If the SDK isn’t ready, it returns thedefaultValue
or control
:
SDK Ready
Once ready, hooks return the server-evaluated value:- Client-side SDKs can bootstrap via
LocalStorage
or an initial flag set—values apply until the SDK is ready. - See Flag Evaluation: Overview.
Usage
Evaluate Flags
Evaluates a feature flag for user context. Applies targeting rules, rollouts, and defaults values.FlagSync CLI
When using the CLI, flag values are automatically inferred from the generated types:An Impression is automatically logged either of the flag hooks are called.
Track Events
Submit user actions with theuseTrack
hook, which supports two usage patterns:
1
With a pre-filled event key
Bind the hook to a specific event key for repeated tracking:
2
With a dynamic event key
Use a generic track function to specify the event key at call time:
- See JavaScript SDK: Track Events for more on
track()
. - See Events: Tracking to learn about numeric and property events.
SDK Event Listeners
The SDK emits these events for SDK lifecycle management:SDK_UPDATE
: Emitted when flags are updatedSDK_READY
: Emitted when the SDK is readySDK_READY_FROM_STORE
: Emitted when flags are loaded from storageERROR
: Emitted when an error occurs during initialization
useFlagSyncClient
hook:
SDK_UPDATE
does not fire if syncing is disabled.Configuration
Configure the SDK with theFsConfig
interface:
Custom Attributes
Define user attributes for targeting in Flags: User Segments.Ensure the
key
in FsUserContext
is unique and persistent for accurate MAU tracking and consistent flag evaluations. See User Context Best Practices for details.Flag Syncing
Configure flag update strategies with thesync
object: stream
, poll
, or off
.
By default, flag updates propagate in milliseconds via server-side events (SSE), ensuring the latest values are used in evaluations.
- Components using flag hooks re-render automatically—no event listeners needed.
- To disable this behavior, set
sync
tooff
, requiring a page refresh to fetch updated flags.
1
Stream (Default)
Stream updates via SSE—flag updates are reevaluated on the server and sent to the client:
2
Polling
Poll the server on an interval:
3
Off
Disable syncing:
Bootstrapping
Initialize the SDK with a set of bootstrap flags:Bootstrapped values apply before the SDK is ready—see Flag Evaluation: Overview.
Storage
Choose between memory and LocalStorage storage types:1
Memory (Default)
2
LocalStorage
Use the
useFlagSyncClient
to get the client.isReadyFromStore
property.Best Practices
- Use
isReady
checks to handle loading states. See Wait for Readiness. - Select a sync strategy (
stream
/poll
/off
) based on your application’s needs. - Use
useTrack
for consistent event tracking in components. - Add user attributes for targeted feature rollouts.
- Consider bootstrapping for faster initial renders.
Environment Variables
Set the following environment variable:FLAGSYNC_SDK_KEY
: Your client-side FlagSync SDK key (required)