Node.js SDK Reference

Updated 1 month 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 the 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 install @harnessio/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 organizing JavaScript code.

const pkg = require('@harnessio/ff-nodejs-server-sdk');
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 are used to define rules for your feature flags and target groups.

const target = {
identifier: 'harness',
name: 'Harness',
attributes: {
'email': '[email protected]'
}
};

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.

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');

Step 5: Add Methods to Register the Events

This method provides a way to register a listener for different events that might be triggered by the SDK, indicating a specific change in the SDK.

You can listen to the following events:

  • Event.READY - SDK successfully initialized
  • Event.FAILED - SDK throws an error
  • Event.CHANGED - any new version of the flag or segment triggers this event. If a segment is changed then it will find all flags with the segment match operator.

Methods to register an event:

on(Event.READY, () => {
console.log('READY');
});

on(Event.FAILED, () => {
console.log('FAILED');
});

on(Event.CHANGED, (identifier) => {
console.log('Changed', identifier);
});

When the listener is not needed, you can remove the desired listener from the internal list to avoid unexpected behavior.

If you want to remove the functionReference listener for Event.READY:

off(Event.READY, functionReference);

If you want to remove all listeners on Event.READY:

off(Event.READY);

If you call off() without parameters it will close the client.

All events are applicable to off() function.

Verify Flag Configuration Updates

Run the application from your IDE and verify whether the flag variation value displayed on your application page is consistent with the feature flag you created.

By toggling the flag on/off in Harness UI, the latest features are synced and the updated flag variation is served. Toggle the flag to verify if your application is getting updated.

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 a 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);


Please Provide Feedback