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


Node.js SDK reference (server-side)

Read time: 2 minutes
Last edited: Oct 26, 2021


This reference guide documents all of the methods available in the Node.js SDK, and explains in detail how these methods work. LaunchDarkly's 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.

For use in server-side applications only

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

To learn more, 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:

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

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

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

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:

1client = LaunchDarkly.init("YOUR_SDK_KEY");
LDClient must be a singleton

It's important to make this a singleton. The client instance maintains internal state that allows us to serve feature flags without making any remote requests. Be sure that you're not instantiating a new client with every request.

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

Using client, 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 client.variation code so that it is invoked as desired.

Here is an example:

1client.once("ready", () => {
2 client.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 });

Lastly, when your application is about to terminate, shut down client. 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.
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().
9client.once("ready", () => {
10 client.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 }
18 // ADDED: shut down the client, since we're about to quit
19 client.close();
20 });

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
2client.variation("any.feature.flag", user, false).then((value) => {
3 // application code
6// Using "await" instead, within an async function
7var value = await client.variation("any.feature.flag", user, false);

There is also an alternative to the ready event:

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

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: