Skip to main content

​
Overview

The @flagsync/node-sdk integrates into Node.js applications for server-side feature management and event tracking—ideal for backend services and APIs.

npm

Latest version available on npm

GitHub

Explore the source code on GitHub

​
Installation

Install the SDK with your preferred package manager: 
npm install @flagsync/node-sdk
npm install -D @flagsync/cli

​
Quickstart

A basic example of using the SDK in a Node.js application (e.g., an Express server): 
import express, { Request, Response } from 'express';
import { FlagSyncFactory, FsUserContext } from '@flagsync/node-sdk';
import { getFlagSyncUserContext } from '@/lib/flagsync/user-context';

const app = express();
const port = 3000;

// Initialize the SDK
const factory = FlagSyncFactory({ sdkKey: 'your-sdk-key'});

// Get the client
const client = factory.client();

// Wait for SDK readiness
await client.waitForReady();

app.get('/', async (req: Request, res: Response) => {
  const ctx = getFlagSyncUserContext(req);

  // Evaluate a flag with user context
  const isEnabled: boolean = client.flag(ctx, 'feature-enabled', false);

  if (isEnabled) {
    res.send('Feature is ON');
  } else {
    res.send('Feature is OFF');
  }
});

app.listen(port, () => {
  console.log(`Server is running on http://localhost:${port}`);
});
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: 
import { FlagSyncFactory } from '@flagsync/node-sdk';

const factory = FlagSyncFactory({
  sdkKey: 'your-sdk-key'
});

const client = factory.client();

​
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

await client.waitForReady();
// SDK is ready
2

Events

import { FsEvent } from '@flagsync/node-sdk';

client.once(FsEvent.SDK_READY, () => {
  // SDK is ready
});

​
SDK Not Ready

If the SDK isn’t ready, it returns the defaultValue or control: 
// SDK not ready
client.flag(ctx, 'flag-one', false); // false (defaultValue)
client.flag(ctx, 'flag-two');        // "control"

​
SDK Ready

Once ready, flag() returns the server-evaluated value: 
await client.waitForReady();
const value = client.flag(ctx, 'flag-one'); // Server-evaluated value

​
User Context Identification

Define the user context with a helper function that returns an FsUserContext 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
export function getFlagSyncUserContext(req): FsUserContext {
  const userId = req.cookies['user-id'];
  const visitorId = req.cookies['visitor-id'];

  return {
    key: userId ?? visitorId,
    attributes: {
      userAgent: req.headers['user-agent'],
      region: req.headers['x-region'],
    }
  };
}
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
import { nanoid } from 'nanoid';
import { verify } from 'jsonwebtoken';

export function identifyUser(req, res, next) {
  // Replace this with your own logic to identify the user
  const user = verify(req.cookies['jwt'], process.env.JWT_SECRET)

  if (user?.userId) {
    // Set the user-id cookie
    res.cookie('user-id', user.userId);
  } else {
    // Set the visitor-id cookie
    const visitorId = req.cookies['visitor-id'] ?? nanoid();
    res.cookie('visitor-id', visitorId);
  }

  next();
}
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
import express from 'express';
import cookieParser from 'cookie-parser';
import { identifyUser } from '@/lib/flagsync/identify';
import { getFlagSyncUserContext } from '@/lib/flagsync/user-context';

const app = express();
app.use(cookieParser());
app.use(identifyUser);  // Identify user middleware

app.post('/feature', async (req, res) => {
  const ctx = getFlagSyncUserContext(req);
  const isEnabled = client.flag(ctx, 'feature-enabled', false);
  res.status(200).json({ enabled: isEnabled });
});

​
Usage

​
Evaluate Flags

Evaluates a feature flag for a given user context. Applies targeting rules, rollouts, and defaults values. 
client.flag<T>(ctx: FsUserContext, flagKey: string, defaultValue?: T): T
app.ts
app.post('/feature', async (req, res) => {
  const ctx = getFlagSyncUserContext(req);
  const isEnabled = client.flag(ctx, 'feature-enabled', false);
  res.status(200).json({ enabled: isEnabled });
});

​
FlagSync CLI

When using the CLI, flag values are automatically inferred from the generated types: 
client.flag(ctx, 'layout');              // Type: 'v1' | 'v2' | 'v3'
client.flag(ctx, 'killswitch');          // Type: boolean
client.flag(ctx, 'price-discount');      // Type: 0.1 | 0.2
client.flag(ctx, 'price-discount', 0.5); // ❌ TS Error: Invalid default value
client.flag(ctx, 'invalid-flag');        // ❌ TS Error: Invalid flag key
Without generated types, you must manually specify the type: 
client.flag<'v1' | 'v2'>(ctx, 'layout');            // Type: 'v1' | 'v2'
client.flag<number>(ctx, 'price-discount');         // Type: number
client.flag<boolean>(ctx, 'enable-feature', false); // Type: boolean (defaultValue must be true or false)
client.flag(ctx, 'no-type')                         // Type: unknown
An Impression is automatically registered when flag() is called.

​
Track Events

Submit user actions with the track() function: 
app.post('/checkout', async (req: Request, res: Response) => {
  const request: PurchaseRequest = req.body;
  const ctx: FsUserContext = {
    key: 'user-123',
    email: 'user@example.com',
  };

  client.track(ctx, 'purchase-request', null, request);

  const t0 = Date.now();
  const order = await makePurchase(request);
  const receipt = await sendOrder(order);
  const t1 = Date.now();

  client.track(ctx, 'purchase-duration', t1 - t0);

  res.status(200).json({ success: true, receipt });
});
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 updated
  • SDK_READY: Emitted when the SDK is ready
  • ERROR: Emitted when an error occurs during initialization
import { FsEvent } from '@flagsync/node-sdk';

// Flag updates
client.on(FsEvent.SDK_UPDATE, () => {
  console.log(`Flags updated at ${new Date().toISOString()}`);
});
SDK_UPDATE does not fire if syncing is disabled.

​
Error Handling

import { FsServiceError } from '@flagsync/node-sdk';

// Via events
client.on(FsEvent.ERROR, (error: FsServiceError) => {
  console.error('SDK Error:', error);
});

// Via promises
try {
  await client.waitForReadyCanThrow();
} catch (error) {
  console.error('Initialization Error:', error as FsServiceError);
}
All exposed errors are normalized to FsServiceError.

​
Configuration

Configure the SDK with the FsConfig interface: 
export interface FsConfig {
  sdkKey: string;
  sync?: {
    type?: 'stream' | 'poll' | 'off'; // Optional: Sync strategy
    pollRate?: number;                // Optional: Polling interval in seconds
  };
  tracking?: {
    impressions?: {
      maxQueueSize: number;           // Required: Max impressions queue size
      pushRate: number;               // Required: Impressions push rate
    };
    events?: {
      maxQueueSize: number;           // Required: Max events queue size
      pushRate: number;               // Required: Events push rate
    };
  };
  urls?: {
    sdk?: string;                     // Optional: SDK endpoint URL
  };
  logger?: Partial<ILogger>;          // Optional: Custom logger
  logLevel?: LogLevel;                // Optional: Logging level
  metadata?: Record<string, any>;     // Optional: Additional metadata
}

​
Custom Attributes

const ctx: FsUserContext = {
  key: 'user-123',
  attributes: {
    plan: 'premium',
    country: 'US',
    userType: 'enterprise'
  }
}
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 the sync 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:
const factory = FlagSyncFactory({
  sdkKey: 'your-sdk-key',
  sync: {
    type: 'stream'
  }
});
2

Polling

Poll the server on an interval:
const factory = FlagSyncFactory({
  sdkKey: 'your-sdk-key',
  sync: {
    type: 'poll',
    pollRate: 60
  }
});
3

Off

Disable syncing:
const factory = FlagSyncFactory({
  sdkKey: 'your-sdk-key',
  sync: {
    type: 'off'
  }
});

​
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)