Overview
The@flagsync/node-sdk
integrates into Node.js applications for server-side feature management and event tracking—ideal for backend services and APIs.
Installation
Install the SDK with your preferred package manager:Quickstart
A basic example of using the SDK in a Node.js application (e.g., an Express server):See User Context Identification for details on the
getFlagSyncUserContext
object.Initialization
Get Your SDK Key
Find your server-side SDK key in your workspace settings. Keep this key private and secure.Initialize the SDK
Initialize the SDK with your SDK key:Wait for Readiness
Use promises or events to ensure the SDK is ready before evaluating flags. Always wait for SDK initialization before evaluating any flags. Initialization usually completes within 30–50ms, depending on flag count and ruleset complexity.1
Promises
2
Events
SDK Not Ready
If the SDK isn’t ready, it returns thedefaultValue
or control
:
SDK Ready
Once ready,flag()
returns the server-evaluated value:
User Context Identification
Define the user context with a helper function that returns anFsUserContext
object. Pass this object to flag()
and track()
functions.
User contexts enable personalized flag evaluations via Individual Targeting and consistent experiences during Percentage Rollouts.
Ensure the
key
in FsUserContext
is unique and persistent for accurate MAU tracking and consistent flag evaluations. See User Context Best Practices for details.1
Create a Helper Function
Create a helper function to construct the user context from request cookies, headers, or your application’s auth system.Adjust the file below to meet your needs.
lib/flagsync/user-context.ts
The
key
is set using a persistent userId
or visitorId
from cookies, falling back to a generated ID with nanoid()
. For proper MAU tracking and consistent flag evaluations, ensure this key
is unique and persistent across requests—see User Context Best Practices.2
Set Cookies in Middleware (Optional)
Use Express middleware to set user identification cookies, simplifying context retrieval in the helper function.
Middleware is optional—user identification logic can be implemented directly in
getFlagSyncUserContext()
or elsewhere in your application.lib/flagsync/identify.ts
3
Use the Helper in Routes
In your Express routes, use the helper to build the
FsUserContext
for flag evaluations or event tracking.app.ts
Usage
Evaluate Flags
Evaluates a feature flag for a given user context. Applies targeting rules, rollouts, and defaults values.app.ts
FlagSync CLI
When using the CLI, flag values are automatically inferred from the generated types:An Impression is automatically registered when
flag()
is called.Track Events
Submit user actions with thetrack()
function:
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 readyERROR
: Emitted when an error occurs during initialization
SDK_UPDATE
does not fire if syncing is disabled.Error Handling
All exposed errors are normalized to
FsServiceError
.Configuration
Configure the SDK with theFsConfig
interface:
Custom Attributes
- Define user attributes for targeting in Flags: User Segments.
- See User Context Identification for the recommended approach to building the context.
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.
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:
Best Practices
- Wait for SDK readiness before evaluating flags.
- Select a sync strategy (
stream
/poll
/off
) based on your application’s needs. - Follow User Context Identification for simplified context management.
- Add user attributes for targeted feature rollouts.
Environment Variables
Set the following environment variable:FLAGSYNC_SDK_KEY
: Your server-side FlagSync SDK key (required)