No results for ""
EXPAND ALL
  • Home
  • API docs

GIVE DOCS FEEDBACK

Node.js SDK reference (client-side)

Read time: 6 minutes
Last edited: Jun 14, 2024
Version 3 of the Node.js SDK replaces users with contexts

A context is a generalized way of referring to the people, services, machines, or other resources that encounter feature flags in your product. Contexts replace another data object in LaunchDarkly: "users."

Code samples on this page are from the two most recent SDK versions where they differ. To learn more about upgrading, read Node.js SDK 2.x to 3.0 migration guide.

Overview

This topic documents how to get started with the client-side Node.js SDK, and links to reference information on all of the supported features.

SDK quick links

LaunchDarkly's SDKs are open source. In addition to this reference guide, we provide source, API reference documentation, and a sample application:

ResourceLocation
SDK API documentationSDK API docs
GitHub repositorynode-client-sdk
Sample applicationNode.js (client-side)
Published modulenpm
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, server-side, and edge 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.

The sample code snippets for this SDK are available in both JavaScript and TypeScript, where the sample code differs. To learn more, read Using LaunchDarkly with TypeScript.

Get started

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

Install the SDK

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');
The Node.js (client-side) SDK uses a client-side ID

The Node.js (client-side) SDK uses a client-side ID. Client-side IDs are specific to each project and environment. They are available from the Environments list for each project. To learn more about key types, read Keys.

Initialize the client

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.

Never embed a server-side SDK key into a client-side application

Client-side IDs are not secret and you can expose them in your client-side code without risk. However, 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 for each LaunchDarkly project. 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.

If you have multiple LaunchDarkly projects, you can create one LDClient for each. In this situation, the clients operate independently. For example, they do not share a single connection to LaunchDarkly.

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 context = {
kind: 'user',
key: 'user-key-123abc'
};
const client = LaunchDarkly.initialize('client-side-id-123abc', context);

When you initialize the client, you can optionally provide configuration options. To learn how, read Configuration. To learn more about the specific configuration options available in this SDK, read LDOptions.

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', () => {
// initialization succeeded, flag values are now available
const flagValue = client.variation('flag-key-123abc', false);
// etc.
});

Subscribe to flag changes

The SDK does not subscribe to streaming real-time updates automatically when you initialize it.

In some cases, streaming may not be necessary. For example, if you reload your entire application on each update, you will get all the flag values again when the client is re-initialized. If this is your use case, you should leave the streaming value undefined, which is the default.

In other cases, streaming may be required. Subscribing to streaming is the only way to receive real-time updates. If you determine that streaming is necessary for your application, there are two ways to subscribe to streaming:

  • Explicitly subscribe to streaming: If you set the streaming configuration option to true, the client will always attempt to maintain a streaming connection.
  • Register a change listener: If you specify an event handler with client.on('change') the client will open a streaming connection. It will close this streaming connection when you unsubscribe from the event, for example by calling client.off('change'). Because opening and closing streaming connections can be expensive, you should explicitly enable streaming if your application frequently starts and stops listening to 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 context will receive the fallback 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.

Shut down the client

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

Supported features

This SDK supports the following features: