JavaScript

@flagsync/js-sdk is an isomorphic library capable of running on Node.js and web browsers. However, it is meant for single-user contexts in browser environments, such as mobile or desktop web applications.

• Compatible with Node.js 16+ and ES5.

• TypeScript is fully supported.

Note on Node.js

While this SDK is stable in Node.js 16+, this is to support uncommon, one-off cases where you may need to initialize feature flags for a single user server-side.

For server-side applications, including SSR web applications, we strongly recommend using the Node.js SDK.

GitHub - flagsync/javascript-client: FlagSync SDK for JavaScriptGitHub

---

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

SDK keys are found within your organization's workspace settings.

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.

Node / JavaScript

# npm
npm install @flagsync/js-sdk

# yarn
yarn add @flagsync/js-sdk

# pnpm
pnpm add @flagsync/js-sdk

---

Getting started

Here's a simple example that shows the most basic usage of the SDK:

import { FlagSyncFactory } from '@flagsync/js-sdk';

const factory = FlagSyncFactory({
  sdkKey: 'YOUR_SDK_KEY',
  core: {
    key: 'userId_0x123',
  },
});

const client = factory.client();

// With async/await
await client.waitForReady();
const value = client.flag<string>('my-flag')

// Or, with events
client.once(client.Event.SDK_READY, () => {
  const value = client.flag<string>('my-flag')
});

Initialize the FlagSync client

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.

ESM

import { FlagSyncFactory } from '@flagsync/js-sdk';

const factory = FlagSyncFactory({
  sdkKey: 'YOUR_SDK_KEY',
  core: {
    key: 'userId_0x123',
  },
});

const client = factory.client();

CJS

const { FlagSyncFactory } = require('@flagsync/js-sdk');

const factory = FlagSyncFactory({
  'YOUR_SDK_KEY',
  core: {
    key: 'userId_0x123',
  },
});

const client = factory.client();

Once instantiated, there are two ways to observe the readiness of the SDK: events and promises.

Events

Node / JavaScript

client.once(client.Event.SDK_READY, () => {
  // SDK is ready
  const value = client.flag<string>('my-flag')
});

client.once(client.Event.SDK_READY_FROM_STORE, () => {
  // Emitted once the SDK has loaded flags from LocalStorage.
  // Fires quickly since no network request is required.
  // This data may be stale, and should not be considered a 
  // replacement for the SDK_READY event.
  const value = client.flag<string>('my-flag')
});

The SDK_READY_FROM_STORE event is useful for quickly loading flags from LocalStorage in Web browser environments. This event only fires when using the localstorage storage type; the default is memory.

Promises & async/await

The SDK has two methods that return a promise for initialization, waitForReady and waitForReadyCanThrow. The former is identical to the SDK_READY event.

Node / JavaScript

client
  .waitForReady()
  .then(() => {
    // SDK is ready
    const value = client.flag<string>('my-flag')
  })


// Or with await
await client.waitForReady();
const value = client.flag<string>('my-flag')

The other method, waitForReadyCanThrow, will throw an error if the SDK fails to initialize. This may be helpful in certain situations.

All client-facing errors are normalized to FsServiceError in the SDK.

Node / JavaScript

client
  .waitForReadyCanThrow()
  .then(() => {
    // SDK is ready
    const value = client.flag<string>('my-flag')
  })
  .catch(e => {
    // Initialization failed
    const error = e as FsServiceError;
  });

// Or with await
try {
  await client.waitForReadyCanThrow();
  const value = client.flag<string>('my-flag')
} catch (e) {
  // Initialization failed
  const error = e as FsServiceError;
}

---

Flag evaluation

• The flag method 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, the method will return the default value, or control if one is not provided.

Node / JavaScript

const flagKey: string;
const defaultValue: T

client.flag<T>(flagKey, defaultValue: T)

A flag impression is automatically registered whenever the flag function is called from the SDK.

Example Usage

Node / JavaScript

/**
 *   FlagSync Dashboard
 *
 *   {
 *     "my-flag": "value-1"
 *   } 
 */
// SDK not ready
client.flag<string>('my-flag');            // 'control'
client.flag<string>('my-flag', 'value-2'); // 'value-2'

// SDK ready
client.flag<string>('my-flag');            // 'value-1'
client.flag<string>('my-flag', 'value-2'); // 'value-1'

Flag impressions are automatically registered when the flag function is called.

Learn more about Events.

---

Submit events

Track user actions or events within the application with the track function.

Node / TypeScript

const eventKey: string;
const eventValue: number | null | undefined;
const properties: Record<string, any> | null | undefined;

client.track(eventKey, eventValue, properties)

When you call the track function to submit events, you can optionally provide key-value properties or a numeric eventValue.

We'll discuss the differences below, and when you might choose one over the other.

Example (Page Load Time)

Say you're releasing a new feature and want to ensure page load times have not degraded. Or, you're testing some optimizations and want to validate that they've had a positive effect.

We'll use the eventValue for this type of event.

First, you'll start by submitting an Event.

Node / JavaScript

client.track('page_load_time', 1.42);

Later on, you may create a Metric called "Average Page Load Time" from the page_load_time event to harvest the values.

Finally, you may link this metric with a feature flag in an Experiment to prove your hypothesis.

Learn about Metrics to see how they work alongside events.

Example (Purchase Events)

Say you're releasing a feature that you believe will increase the purchase amounts of your customers. Or, you're testing different discount amounts that you believe will increase the overall number of purchases.

You'll most likely want to track purchase events within your application along with the item purchased.

We'll use properties for this type of event.

Node / JavaScript

const item: Product = { 
  productId: '0x123', 
  price: 49.99,
  discount: 0.20,
  isReturnCustomer: true,
  ...
}

client.track('purchase_event', null, item);

Later on, you may create a Metric called "Average Purchase Price per User" to harvest the price of items submitted with the purchase_event.

Or, you may create a Metric called "Count of Discounts" to track the discount value.

Finally, you may link these metrics with a feature flag in an Experiment to prove your hypothesis.

Learn about Metrics to see how they work alongside events.

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.

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:

Node / JavaScript

const sdkKey = process.env.FLAGSYNC_SDK_KEY
type SyncType = 'stream' | 'poll' | 'off'

const factory = FlagSyncFactory({
  sdkKey: process.env.FLAGSYNC_SDK_KEY
  core: {
    key: string
  },
  sync?: {
    type?: SyncType;
    pollInterval?: number;
  };
});

Listen for Updates

You can listen for updates using the SDK_UPDATE event.

Node / JavaScript

// Ready event
client.once(client.Event.SDK_READY, () => {
  const value = client.flag<string>('my-flag')
  console.log(value) // "value-1"
});

// Update event
client.on(client.Event.SDK_UPDATE, () => {
  const value = client.flag<string>('my-flag')
  console.log(value) // "value-2"
});

---

Custom Attributes

When initializing the factory, you can pass custom attributes about the user or user segment, which are automatically made available in the FlagSync Dashboard for individual targeting.

Node / JavaScript

const factory = FlagSyncFactory({
  sdkKey: 'YOUR_SDK_KEY',
  core: {
    key: 'userId_0x123',
    attributes: {
      {
        "email": "[e-mail]"
        "group: "QA Tester"
        "location": "Boston
      }
    },
  },
});

Create a targeting rule based on the group attribute.

---

Bootstrapping

You can initialize the SDK with a set of flags using the bootstrap configuration. This is useful for setting default values or for testing.

Node / JavaScript

/**
 *   Remote configuration:
 *   {
 *     "my-flag": "value-1"
 *   }
 */

const factory = FlagSyncFactory({
    sdkKey: 'YOUR_SDK_KEY',
    core: {
      key: 'userId_0x123'
    },
    bootstrap: {
      'my-flag': 'value-2'
    }
});

client.flag<string>('my-flag'); // 'value-2'

await client.waitForReady();

client.flag<string>('my-flag'); // 'value-1'

---

Storage

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.

Node / JavaScript

const sdkKey = process.env.FLAGSYNC_SDK_KEY
type StorageType = 'memory' | 'localstorage'

const factory = FlagSyncFactory({
  sdkKey: process.env.FLAGSYNC_SDK_KEY
  core: {
    key: string
  },
  storage?: {
    type?: StorageType;
    prefix?: string;
  };
});

When initializing from LocalStorage, the SDK_READY_FROM_STORE event is fired when the flags have been loaded.

Node / JavaScript

client.once(client.Event.SDK_READY_FROM_STORE, () => {
  const value = client.flag<string>('my-flag')
});

Emitted once the SDK has loaded flags from LocalStorage.

Fires quickly since no network request is required.

This data may be stale, and should not be considered a replacement for the SDK_READY event.

---

FsConfig

You can configure any of the following option arguments when initializing the FlagSyncFactory.

Node / JavaScript

type FsFlagValue = any;
export type FsFlagSet = Record<string, FsFlagValue>;

type CustomAttributeValue = any;
type CustomAttributes = Record<string, CustomAttributeValue>;

type StorageType = 'memory' | 'localstorage';
type SyncType = 'stream' | 'poll' | 'off';

export interface FsConfig {
  /**
   * 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": "[e-mail]"
     *       "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;
}