Node.js SDK reference (server-side)

This reference guide documents all of the methods available in the Node.js SDK, and explains in detail how these methods work. If you want to dig even deeper, our SDKs are open source. To learn more, read Node.js SDK repository on GitHub. The online API docs contain the programmatic definitions of every type and method. Additionally you can clone and run sample applications using this SDK with vanilla JavaScript, TypeScript, and server-side bootstrapping.

Getting started

Building on top of our Getting Started guide, the following steps will get you started with using the LaunchDarkly SDK in your Node.js application.

The first step is to install the LaunchDarkly SDK as a dependency in your application using your application's dependency manager.

Here's how:

1npm install launchdarkly-node-server-sdk --save
2
3# Note that in earlier versions, the package name was ldclient-node
COPY

Next you should import the LaunchDarkly client in your application code:

1const LaunchDarkly = require('launchdarkly-node-server-sdk');
COPY

Once the SDK is installed and imported, you'll want to create a single, shared instance of the LaunchDarkly client. You should specify your SDK key here so that your application will be authorized to connect to LaunchDarkly and for your application and environment.

Here's how:

1ldClient = LaunchDarkly.init("YOUR_SDK_KEY");
COPY

The client will emit a ready event when it has been initialized and can serve feature flags.

Using ldClient, you can check which variation a particular user should receive for a given feature flag. Note that the ready event is only emitted once - when the client first initializes. In a production application you should place your ldClient.variation code so that it is invoked as desired.

Here is an example:

1ldClient.once("ready", () => {
2  ldClient.variation("your.flag.key", {"key": "user@test.com"}, false,
3    (err, showFeature) => {
4      if (showFeature) {
5        // application code to show the feature
6      } else {
7        // the code to run if the feature is off
8      }
9    });
10});
COPY

Lastly, when your application is about to terminate, shut down ldClient. This ensures that the client releases any resources it is using, and that any pending analytics events are delivered to LaunchDarkly. If your application quits without this shutdown step, you may not see your requests and users on the dashboard, because they are derived from analytics events. This is something you only need to do once.

Here's how:

1// This example repeats the code from the previous example because in Node, the client methods are
2// asynchronous, so in order to add another step that happens after the previous steps are finished,
3// we need to add code *inside* the existing block. In other words, do not type the whole thing over
4// again, just modify the last part you added as shown.
5//
6// Again, in a real application, this step is something you would only do when the application is
7// about to quit, not after every call to variation().
8
9ldClient.once("ready", () => {
10  ldClient.variation("your.flag.key", {"key": "user@test.com"}, false,
11    (err, showFeature) => {
12      if (showFeature) {
13        // application code to show the feature
14      } else {
15        // the code to run if the feature is off
16      }
17
18      // ADDED: shut down the client, since we're about to quit
19      ldClient.close();
20    });
21});
COPY

Promises and async

All asynchronous SDK methods which accept a callback also return a Promise. This means that if your application uses promises to manage asynchronous operations, interacting with the SDK should be convenient. Since the async/await syntax is based on Promises, these methods will also work with await.

Here is an example:

1// Using the .then() method to add a continuation handler for a Promise
2ldClient.variation("any.feature.flag", user, false).then((value) => {
3  // application code
4});
5
6// Using "await" instead, within an async function
7var value = await ldClient.variation("any.feature.flag", user, false);
COPY

There is also an alternative to the ready event:

1// Using .then() and .catch() to add success and error handlers to a Promise
2ldClient.waitForInitialization().then((client) => {
3  // initialization complete
4}).catch((err) => {
5  // initialization failed
6});
7
8// Using "await" instead, within an async function
9try {
10  await ldClient.waitForInitialization();
11  // initialization complete
12} catch (err) {
13  // initialization failed
14}
COPY

allFlagsState and flush also return a Promise.

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

Supported features

This SDK supports the following features:

• Aliasing users
• Bootstrapping
• Configuration
• Evaluating flags
• Flag evaluation reasons
• Flushing events
• Getting all flags
• Identifying and changing users
• Logging configuration
• Offline mode
• Secure mode
• Sending custom events
• Shutting down
• Storing data
• Subscribing to flag changes
• User configuration