Skip to main content

Node.js SDK reference

note

This SDK is not currently supported on Harness Self-Managed Enterprise Edition (on premises).

This topic describes how to use the Harness Feature Flags Node.js SDK for your Node.js application.

For getting started quickly, you can use our sample code from the Node.js SDK README. You can also clone and run a sample application from the Node.js SDK GitHub Repository.

Before you begin​

You should read and understand the following:

Version​

Latest SDK version can be found on GitHub Release Page

Requirements​

To use this SDK, make sure you:

Install the SDK​

Install using npm​

npm install @harnessio/ff-nodejs-server-sdk

Install using yarn​

yarn add @harnessio/ff-nodejs-server-sdk

Initialize the SDK​

To initialize the Node.js SDK, you need to:

  1. Import the package.
  2. Add your Server SDK Key to connect to your Harness Environment.
  3. Add a Target that you want to Evaluate against a Feature Flag.
  4. (Optional) Configure the SDK options. For more details on what features you can configure for this SDK, go to Configure the SDK.

Import the package​

CommonJS​

To import with CommonJS, use:

const { Client } = require('@harnessio/ff-nodejs-server-sdk');

ES modules​

To import with ES modules use:

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

Add the Server SDK Key​

To connect to the correct Environment that you set up on the Harness Platform, you need to add the Server SDK Key from that Environment. Input the Client SDK Key into the API_KEY parameter, for example:

const client = new Client('sdkKey');

Add a Target​

Details

What is a Target? Targets are used to control which users see which Variation of a Feature Flag, for example, if you want to do internal testing, you can enable the Flag for some users and not others. When creating a Target, you give it a name and a unique identifier. Often Targets are users but you can create a Target from anything that can be uniquely identified, such as an app or a machine.

For more information about Targets, go to Targeting Users With Flags.

To add a Target, build it and pass in arguments for the following:

ParameterDescriptionRequired?Example
identifierUnique ID for the Target.Read Regex requirements for Target names and identifiers below for accepted characters.Requiredidentifier: 'HT_1'
nameName for this Target. This does not have to be unique.
Note: If you don’t provide a value, the name will be the same as the identifier.Read Regex requirements for Target names and identifiers below for accepted characters.		Optional
Note: If you don't want to send a name, don't send the parameter. Sending an empty argument will cause an error.		name: 'Harness_Target_1'
attributesAdditional data you can store for a Target, such as email addresses or location.Optionalattributes: {
Regex requirements for Target names and identifiers

Identifier

Regex: ^[A-Za-z0-9.@_-]*$
Must consist of only alphabetical characters, numbers, and the following symbols:
. (period)
@ (at sign)
-(dash)
_ (underscore)

The characters can be lowercase or uppercase but cannot include accented letters, for example Cafe_789.

Name Regex: ^[\\p{L}\\d .@_-]*$

Must consist of only alphabetical characters, numbers, and the following symbols:
. (period)
@ (at sign)
-(dash)
_ (underscore)
(space)

The characters can be lowercase or uppercase and can include accented letters, for example Café_123.

For example:

const target = {  
    identifier: 'HT_1',  
    name: 'Harness_Target_1',  
    attributes: {  
       'email': 'demo@harness.io'  
    }  
  };

Configure the SDK​

You can configure the following features of the SDK:

NameDescriptionDefault Value
baseUrlThe URL used to fetch Feature Flag Evaluations. When using the Relay Proxy, change this to: http://localhost:7000https://config.ff.harness.io/api/1.0
eventsUrlThe URL for posting metrics data to the Feature Flag service. When using the Relay Proxy, change this to: http://localhost:7000https://events.ff.harness.io/api/1.0
pollIntervalThe interval in milliseconds that we poll for changes when you are using stream mode.60 (seconds)
enableStreamSet to true to enable streaming mode.Set to false to disable streaming mode.true
enableAnalyticsSet to true to enable analytics.Set to false to disable analytics.Note: When enabled, analytics data is posted every 60 seconds.true

For example:

// Create Options  
const options = {  
  baseUrl: "http://localhost:7000",  
  eventsUrl: "http://localhost:7000"  
}

Complete the initialization​

To complete the initialization:

  1. Create an instance of the Feature Flag client and pass in the Server SDK Key and configuration options:
// Create client with options  
const client = new Client(apiKey, options);
  1. Wait for the SDK to complete initialization and to fetch the Flag data:
await client.waitForInitialization();

Evaluate a Flag​

Evaluating a Flag is when the SDK processes all Flag rules and returns the correct Variation of that Flag for the Target you provide. 

If a matching Flag can’t be found, or the SDK can’t remotely fetch flags, the default value is returned. 

There are different methods for the different Variation types and for each method you need to pass in:

  • Identifier of the Flag you want to evaluate
  • The Target object you want to evaluate against
  • The default Variation

For example:

Evaluate a boolean Variation​

function boolVariation(  
  identifier: string,  
  target: Target,  
  defaultValue: boolean = true,  
): Promise<boolean>;

Evaluate a string Variation​

function stringVariation(  
  identifier: string,  
  target: Target,  
  defaultValue: boolean = '',  
): Promise<string>;

Evaluate a number Variation​

function numberVariation(  
  identifier: string,  
  target: Target,  
  defaultValue: boolean = 1.0,  
): Promise<number>;

Evaluate a JSON Variation​

function jsonVariation(  
  identifier: string,  
  target: Target,  
  defaultValue: boolean = {},  
): Promise<Record<string, unknown>>;

Listen for events​

Register the event listener​

You can listen for the following events:

  • Event.READY - Indicates the SDK was successfully initialized.
  • Event.FAILED - Indicates the SDK had thrown an error.
  • Event.CHANGED - Indicates a Flag or Segment has been updated.

For example:

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

Close the event listener​

To avoid unexpected behavior, when the listener isn't needed, turn it off.

To remove the functionReference listener for Event.READY, use:

off(Event.READY, functionReference);

To remove all listeners, use:

off(Event.READY);

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

Test your app is connected to Harness​

When you receive a response showing the current status of your Feature Flag, go to the Harness Platform and toggle the Flag on and off. Then, check your app to verify if the Flag Variation displayed is updated with the Variation you toggled.

note

The SDK must run for at least 60 seconds before it sends metrics. Please ensure metrics have not been disabled in the SDK.

Close the SDK client​

In most applications, you won't need to close the SDK client.

However, you should close the SDK client if:

  • Your application is about to terminate. Closing the client ensures that all associated resources are released.
  • You have determined that you do not need to evaluate flags again in your application lifecycle.
important

The SDK does not evaluate flags after the client is closed.

To close the SDK, call the following function:

function close(): void;

Additional options​

Configure your logger​

You can provide your own logger to the SDK by passing it in as a config option. The following example creates an instance of the winston logger, sets the level to DEBUG, and passes it to the client.

const winston = require('winston')  
  
// Create client with logger  
const client = new Client(apiKey, {  
  logger: new winston.createLogger({  
    level: 'debug',  
    transports: [new winston.transports.Console()]  
  })  
});

Sample code for a Node.js application​

Here is a sample code for using the SDK with a Node.js application:

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

Troubleshooting​

The SDK logs the following codes for certain lifecycle events, for example authentication, which can aid troubleshooting.

CodeDescriptionLog Level
1000Successfully initializedInfo
1001Failed to initialize due to authentication errorError
1002Failed to initialize due to a missing or empty API keyError
1003WaitForInitialization configuration option was provided and the SDK is waiting for initialization to finishInfo
2000Successfully authenticatedInfo
2001Authentication failed with a non-recoverable errorError
2002Authentication failed and is retryingWarn
2003Authentication failed and max retries have been exceededError
3000SDK closingInfo
3001SDK closed successfullyInfo
4000Polling service startedInfo
4001Polling service stoppedInfo
5000Streaming connectedInfo
5001Streaming disconnectedWarn
5002Streaming event receivedDebug
5003Streaming disconnected and is retrying to connectInfo
5004Streaming service stoppedInfo
5005Stream is still retrying to connect after 4 attemptsWarn
6000Evaluation was successfulDebug
6001Evaluation failed and the default value was returnedInfo
7000Metrics service has startedInfo
7001Metrics service has stoppedInfo
7002Metrics posting failedWarn
7003Metrics posting successDebug
7004Metrics max target size exceededWarn
7007Metrics max evaluation size reachedWarn