• HOME
  • INTEGRATIONS
  • SDKS
  • GUIDES
  • API DOCS
No results for ""
EXPAND ALL
launchdarkly.com

EDIT ON GITHUB

Node.js SDK reference (server-side)

Read time: 2 minutes
Last edited: Jun 18, 2021

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.

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

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.

1npm install launchdarkly-node-server-sdk --save
2
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.

1ldClient = 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 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.

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});

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.

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});

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.

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);

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}

allFlagsState and flush also return a Promise.

Supported features

This SDK supports the following features: