Node.js SDK Reference

Updated 5 days ago by Megha Mathur

This topic explains how to use the Harness Feature Flags (FF) SDK in your Node.js application. To learn more about using a sample FF SDK code with Node.js application, see the Node.js SDK GitHub repository.

In this topic:

Before You Begin

Prerequisites

  1. Create a feature flag in Harness Feature Flags. Feature flags wrap your code and allow you to manage the feature release in a controlled way. See Create a Feature Flag.
  2. Ensure that you have created your SDK Key. See Create an SDK Key.
  3. A Node.js application to test your feature flag. If you do not have your Node.js Application, you can download a sample application from the Node.js SDK GitHub repository.
    1. On the Node.js SDK GitHub page, click Code and then clone the sample application. For more information, see Cloning a repository.
    2. Import your project in an IDE such as WebStorm or Visual Studio Code.

Use Harness Feature Flags SDKs with Node.js Applications

Perform the following steps to get started with using the Feature Flags SDK in your Node.js application:

Step 1: Install the FF SDK Dependency

The first step is to install the FF SDK as a dependency in your application using your application's dependency manager.

npm i @harness/ff-nodejs-server-sdk

Step 2: Authorize your Application to Connect to the FF Client

After installing the SDK, enter the SDK keys that you created for your environment. The SDK keys authorize your application to connect to the FF client. You can use Common JS or ESM for your application.

CommonJS

CommonJS is a module formatting system. It is a standard for structuring and organising JavaScript code. CJS helps in the server-side development of apps and it's format has heavily influenced Node.js's module management

const pkg = require('sdkKey');
const { Client } = pkg;

const client = new Client('sdkKey', {
enableStream: true,
});

setInterval(() => {
const target = {
identifier: 'harness',
};
const value = client.boolVariation('test', target, false);
console.log('Evaluation for flag test and target: ', value, target);
}, 10000);

ESM

import { Client } from 'ff-nodejs-server-sdk';

const client = new Client('sdkKey');

setInterval(() => {
const value = client.boolVariation('test', null, false);
console.log("Evaluation for flag test and target none: ", value);
}, 10000);

Step 3: Add a Target

Targets are used to control which user sees the variation of a feature flag. You can add targets and define their attributes in your code directly as well. The targets added in the application code are discovered automatically and populated in the Harness UI.

  • A target can be any attribute that can be uniquely identified with an entity.
  • A target is identified by a name and an identifier.
    • Enter a name that will identify this target.
    • Enter a unique identifier for your target. For example, an application, systems, services, machines, resources uniquely identified by an IP address, email ID, user ID, etc.
    • See Target Management.
Add Individual Target
const target = {
identifier: 'harness',
};
Add a Target with Attributes

Attributes are the properties of your target and used to define rules for your feature flags and target groups.

const target = {
identifier: 'harness',
name: 'Harness',
attributes: {
'email': 'xyz.abc@harness.io'
}
};

Step 4: Evaluate Target for your Feature Flag

Once you have added the target, evaluate the target for your feature flag. A feature flag is evaluated for a particular target.

const value = client.boolVariation('test', target, false);

The <feature_identifier> is your feature flag identifier. When you name a feature flag, Harness automatically generates its identifier. For more information, see Entity Identifier Reference and Create a flag type. need clarification wrt to above code; what is the identifier here etc

Sample Code for Boolean Flag Type

Here are the sample codes:

Bool Variation

const value = client.boolVariation('test', target, false);

Number Variation

const value = client.numberVariation('test', target, 1);

String Variation

const value = client.stringVariation('test', target, '');
Sample Code for Multivariate

Here are the sample codes:

Number Type

const value = client.jsonVariation('test', target, {});

String Type

const value = client.stringVariation(COLOR_FEATURE_KEY, target, 'black');

Sample FF SDK for Node.js Application

Here is a sample code for using FF SDKs with Node.js applications.

To learn more about using a sample CF SDK code with Node.js application, see the Node.js SDK GitHub repository.


const pkg = require('ff-nodejs-server-sdk');
const { Client } = pkg;

const client = new Client('1c100d25-4c3f-487b-b198-3b3d01df5794', {
enableStream: true,
pollInterval: 2 * 60 * 1000 // two min pollInterval
});

setInterval(() => {
const target = {
identifier: 'harness',
};
const value = client.boolVariation('test', target, false);
console.log('Evaluation for flag test and target: ', value, target);
}, 10000);

Verify Flag Configuration Updates

SDK maintains all the feature flag details locally in its cache and evaluates flags based on it. The SDKs use streaming and a polling strategy to keep the local cache in sync with the flag configurations.

Streaming Mode

Polling Mode

  • In the case of streaming mode, a connection is open to the stream endpoint.
  • Anytime flag configuration updates, a stream event (indicating which flag/target group changed) is pushed to the application on this connection.
  • SDK fetches the latest flag configuration for the flag/target group specified in the event and updates the cache.

Config is polled periodically (default 60 seconds), and the cache is updated.


Please Provide Feedback