JavaScript SDK Reference

Updated 1 month ago by Archana Singh

This topic explains how to use the Harness Feature Flags SDK in your JavaScript application. To learn more about using Feature Flags SDK with JavaScript application, clone and run a sample application from the JavaScript SDK GitHub repository.

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. Download the Harness Feature Flag JavaScript Client SDK.
  4. A JavaScript application to test your feature flag. If you do not have your JavaScript Application, you can download a sample application from the JavaScript SDK GitHub repository.
    1. On the JavaScript Client 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 IntelliJ or Eclipse.

Use Harness Feature Flags SDKs with JavaScript Applications

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

Step 1: Install the JavaScript Feature Flag Client SDK

To install the Harness Feature Flag JavaScript client SDK in your application, simply run the following npm or yarn command:

npm i @harnessio/ff-javascript-client-sdk

or

yarn add @harnessio/ff-javascript-client-sdk

Step 2: Import the Feature Flag Client SDK

Import the client using the following command:

import { initialize, Event } from '@harnessio/ff-javascript-client-sdk'

Import Using unpkg

Refer to the Harness Feature Flag JavaScrip SDK to identify the latest version for your build automation tool.

If you wish to import the library directly without having to use npm or yarn, run the following command:

<script type="module">
  import { initialize, Event } from 'https://unpkg.com/@harnessio/ff-javascript-client-sdk@1.4.9/dist/sdk.client.js'
</script>

If your browser does not support the ES modules, then run the following command:

<script src="https://unpkg.com/@harnessio/ff-javascript-client-sdk@1.4.9/dist/sdk.client.js"></script>
<script>
  var initialize = HarnessFFSDK.initialize
  var Event = HarnessFFSDK.Event
</script>

Ensure that you verify the version in the unpkg URL.

Step 3: Initialize the SDK

Now that the SDK is imported, you can configure and initialize it. You should enter your SDK keys when configuring the SDK so that your application is authorized to connect to Harness Feature Flags and retrieve flags for your environment.

initialize(FeatureFlagSDKKey: string, target: Target, options?: Options)

In which Target and Options are defined as:

interface Target {
  identifier: string
  name?: string
  anonymous?: boolean
  attributes?: object
}

interface Options {
  baseUrl?: string
  debug?: boolean
}

For example:

const cf = initialize('00000000-1111-2222-3333-444444444444', {
    identifier: YOUR-TARGET-IDENTIFIER,      // Target identifier
    name: YOUR-TARGET-NAME,                  // Optional target name
    attributes: {                            // Optional target attributes
      email: 'sample@sample.com'
    }
  });

Step 4: Listen to the  cf Instance Events

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

cf.on(Event.READY, flags => {
  // Event happens when connection to server is established
  // flags contains all evaluations against SDK key
})

cf.on(Event.CHANGED, flagInfo => {
  // Event happens when a changed event is pushed
  // flagInfo contains information about the updated feature flag
})

cf.on(Event.DISCONNECTED, () => {
  // Event happens when connection is disconnected
})

cf.on(Event.ERROR, () => {
  // Event happens when some connection error has occurred
})

Step 5: Evaluate Target for Your Feature Flag

Once you have initialized the Feature Flag client for a target, evaluate it for your feature flag. A feature flag is evaluated for a particular target.

const value = cf.variation('Dark_Theme', false) // second argument is default value when variation does not exist

Step 6: Remove Listeners

Remove a listener of an event using cf.off.

cf.off(Event.ERROR, () => {
  // Do something when an error occurs
})

Remove all listeners.

cf.off()

On closing your application, call cf.close() to close the event stream.

cf.close();

Step 7: Verify Your Feature Flag

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.

Toggle the flag on and off to verify if your application is getting updated.

Sample Code for JavaScript Application

Here is a sample code for using Harness Feature Flag SDKs with JavaScript application. To learn more about using the sample JavaScript application, see the JavaScript SDK GitHub repository.

import React, { useEffect, useState } from 'react'
import ReactDOM from 'react-dom'
import { initialize, Event } from '@harnessio/ff-javascript-client-sdk'

const App = () => {
  const [featureFlags, setFeatureFlags] = useState({})

  useEffect(() => {
    const cf = initialize(
      '00000000-1111-2222-3333-444444444444',
      {
        identifier: 'Harness',
        attributes: {
          lastUpdated: Date(),
          host: location.href
        }
      },
      {
        debug: true,
        baseUrl: 'http://22.299.167.189/api/1.0', // QA
        eventUrl: 'http://21.73.236.95/api/1.0'
      }
    )

    cf.on(Event.READY, flags => {
      setFeatureFlags(flags)
    })

    cf.on(Event.CHANGED, flagInfo => {
      if (flagInfo.deleted) {
        setFeatureFlags(currentFeatureFlags => {
          delete currentFeatureFlags[flagInfo.flag]
          return { ...currentFeatureFlags }
        })
      } else {
        setFeatureFlags(currentFeatureFlags => ({ ...currentFeatureFlags, [flagInfo.flag]: flagInfo.value }))
      }
    })

    return () => {
      cf.close()
    }
  }, [])

  return <pre>{JSON.stringify(featureFlags, null, 2)}</pre>
}

ReactDOM.render(<App />, document.getElementById('root'))

Please Provide Feedback