Node.js SDK reference (server-side)

Read time: 2 minutes

Last edited: Jan 20, 2022

Overview

This reference guide documents all of the methods available in the server-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 with vanilla JavaScript, TypeScript, or server-side bootstrapping.

For use in server-side applications only

This SDK is intended for use in multi-user Node.js server applications. If you want to set up LaunchDarkly in JavaScript in a browser environment, read the JavaScript SDK reference. If you're creating a client-side Node application, read the Node SDK reference. If you're creating a desktop application in Electron, read the Electron SDK reference.

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

Getting started

After you complete the Getting Started process, follow these instructions to start 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:

npm install launchdarkly-node-server-sdk
# In earlier versions, the package name was ldclient-node

Next, import the LaunchDarkly client in your application code:

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

After you install and import the SDK, create a single, shared instance of LDClient. Specify your SDK key here to authorize your application to connect to a particular environment within LaunchDarkly.

Here's how:

client = LaunchDarkly.init("YOUR_SDK_KEY");

LDClient must be a singleton

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

The client emits a ready event when you initialize it and it can serve feature flags.

Using client, you can check which variation a particular user will receive for a given feature flag. The ready event is only emitted once, when you first initialize the client. In a production application, place your client.variation code so that it is invoked as needed.

Here is an example:

client.once("ready", () => {
  client.variation("your.flag.key", {"key": "user@test.com"}, false,
    (err, showFeature) => {
      if (showFeature) {
        // application code to show the feature
      } else {
        // the code to run if the feature is off
      }
    });
});

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. Because the async/await syntax is based on Promises, these methods also work with await.

Here is an example:

// Using the .then() method to add a continuation handler for a Promise
client.variation("any.feature.flag", user, false).then((value) => {
  // application code
});
// Using "await" instead, within an async function
var value = await client.variation("any.feature.flag", user, false);

There is also an alternative to the ready event:

// Using .then() and .catch() to add success and error handlers to a Promise
client.waitForInitialization().then((client) => {
  // initialization complete
}).catch((err) => {
  // initialization failed
});
// Using "await" instead, within an async function
try {
  await client.waitForInitialization();
  // Initialization complete
} catch (err) {
  // Initialization failed
}

allFlagsState and flush also return a Promise.

Shutting down

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

Supported features

This SDK supports the following features: