• Home
  • Integrations
  • SDKs
  • Guides
  • API docs
No results for ""
EXPAND ALL

EDIT ON GITHUB

Node.js SDK reference (client-side)

Read time: 2 minutes
Last edited: Jan 25, 2022

Overview

This reference guide documents all of the methods available in the client-side Node.js SDK, and explains how these methods work. LaunchDarkly's SDKs are open source. The source is available in its GitHub repository and its generated API reference.

You can also use this SDK to clone and run a sample application.

For use in mobile, desktop, and embedded client applications only

This SDK is intended for use in single-user mobile, desktop, and embedded applications. If you have a Node.js application and want to set up LaunchDarkly on the server-side, read the server-side Node.js SDK reference. If you are using Electron, there is an Electron SDK more specifically designed for that environment.

To learn more about LaunchDarkly's different SDK types, read Client-side and server-side SDKs.

This SDK is closely related to the browser JavaScript SDK and has almost exactly the same API, but does not have any browser-specific functionality and adds several features specific to Node.

Getting started

After you complete the Getting Started process, follow these instructions to start using the LaunchDarkly SDK in your Node.js code.

First, install the LaunchDarkly SDK as a dependency in your application using your application's dependency manager.

Here's how:

npm install launchdarkly-node-client-sdk

Next, import the LaunchDarkly client in your application code:

const LaunchDarkly = require('launchdarkly-node-client-sdk');

After you install and import the SDK, create a single, shared instance of LdClient. To create a client instance, you need your environment's client-side ID. This authorizes your application to connect to a particular environment within LaunchDarkly. Your client-side ID is available in the Projects tab of your Account settings page. Client-side IDs are not secret and you can expose them in your client-side code without risk. Never embed a server-side SDK key into a client-side application.

LdClient must be a singleton

It's important to make LdClient a singleton. The client instance maintains internal state that allows LaunchDarkly to serve feature flags without making any remote requests. Do not instantiate a new client with every request.

Feature flag targeting and rollouts are determined by the active user. You must pass a user context to the SDK during initialization before requesting any feature flags with variation. Failure to pass a valid user context to the SDK during initialization will result in an error.

Here's how to initialize the client:

const user = {
key: "aa0ceb"
};
const client = LaunchDarkly.initialize('YOUR_CLIENT_SIDE_ID', user);

The client emits a ready event when you have initialized it. You can also use the waitForInitialization() method, which returns a Promise. After you have initialized it, you can safely call variation to access your feature flags. The SDK emits the ready event only once, when the client first initializes. In a production application, your calls to client.variation would normally not be inside of this event handler.

To emit a ready event:

client.on('ready', () => {
console.log("It's now safe to request feature flags");
const showFeature = client.variation("YOUR_FEATURE_KEY", false);
if (showFeature) {
...
} else {
...
}
});
Streaming updates

The SDK does not subscribe to streaming real-time updates automatically when you initialize it. Setting the streaming option to true in the client configuration causes the SDK to open a streaming connection to LaunchDarkly and receive live feature flag updates. You can also specify an event handler with client.on('change') to be notified immediately when a flag changes.

Making feature flags available to this SDK

You must make feature flags available to client-side SDKs before the SDK can evaluate those flags. If an SDK tries to evaluate a feature flag that is not available, the user will receive the default value for that flag.

To make a flag available to this SDK, check the SDKs using Client-side ID checkbox during flag creation, or on the flag's Settings tab. To make all of a project's flags available to this SDK by default, check the SDKs using Client-side ID checkbox in your project Settings.

Shutting down

Shut down the client when your application terminates. To learn more, read Shutting down.

Supported features

This SDK supports the following features: