Node.js SDK reference (server-side)

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

Overview

This topic documents how to get started with the server-side Node.js SDK. It also links to reference information for all of the features the server-side Node.js SDK supports.

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

Resource	Location
SDK API documentation	SDK API docs
Supported SDK Versions	Node.js server SDK
GitHub repository	node-server-sdk
Sample applications	Node.js (server-side) , Node.js (server-side), TypeScript , Node.js (server-side) with bootstrapping , OpenFeature Node.js (server-side)
Published module	npm

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.js SDK reference (client-side). If you’re creating a desktop application in Electron, read the Electron SDK reference.

To learn more about LaunchDarkly’s different SDK types, read Choosing an SDK type.

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 Getting Started process, follow these instructions to start using the LaunchDarkly SDK in your Node.js application.

Install the SDK

First, install the LaunchDarkly SDK as a dependency in your application using your application’s dependency manager.

We recommend making the LaunchDarkly observability plugin available as well. This plugin collects and sends observability data to LaunchDarkly, including metrics autogenerated from OpenTelemetry data. This means you can review error monitoring, logs, and traces from within the LaunchDarkly UI. They require the Node.js (server-side) SDK version 9.10 or later.

Here’s how:

shell

    npm install @launchdarkly/node-server-sdk

    # optional observability plugin, requires Node.js (server-side) SDK v9.10+
    npm install @launchdarkly/observability-node

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

Next, import the LaunchDarkly client in your application code:

Node.js SDK v8.x+

    import { init, LDContext, LDOptions } from '@launchdarkly/node-server-sdk';

    // optional observability plugin, requires Node.js (server-side) SDK v9.10+
    import { Observability } from "@launchdarkly/observability-node";

The Node.js (server-side) SDK uses an SDK key. Keys are specific to each project and environment. They are available from Project settings, on the Environments list. 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. Specify your SDK key here to authorize your application to connect to a particular environment within LaunchDarkly.

Here’s how:

Node.js SDK

    const client = init(
      'YOUR_SDK_KEY',
      {
        // optional observability plugin, requires Node.js (server-side) SDK v9.10+
        plugins: [ new Observability(), ],
        // other options
      },
    );

To learn more about the specific configuration options available in this SDK, read LDOptions.

It’s important to make LDClient a singleton for each LaunchDarkly project. 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.

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.

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

Evaluate a context

Using client, you can check which variation a particular context 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:

Node.js SDK v7.x and later (JavaScript)

    const context = {
       "kind": 'user',
       "key": 'example-user-key',
       "name": 'Sandy'
    };

    client.on('ready', () => {
      client.variation('example-flag-key', context, 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:

Node.js SDK v7.x and later (JavaScript)

    // Using the .then() method to add a continuation handler for a Promise
    client.variation('example-flag-key', context, false).then((value) => {
      // application code
    });

    // Using "await" instead, within an async function
    const value = await client.variation('example-flag-key', context, false);

There is also an alternative to the ready event:

JavaScript

    // Using .then() and .catch() to add success and error handlers to a Promise
    client.waitForInitialization({timeout: 10}).then((client) => {
      // initialization complete
    }).catch((err) => {
      // timeout or initialization failed
    });

    // Using "await" instead, within an async function
    try {
      await client.waitForInitialization({timeout: 10});
      // initialization complete
    } catch (err) {
      // timeout or initialization failed
    }

allFlagsState and flush also return a Promise.

There is no built-in timeout for this method. Instead, we recommend using Promise.race() for your code to stop waiting on the Promise after a set amount of time. Regardless of whether you continue to wait, the SDK will still retry all connection failures indefinitely unless it gets an unrecoverable error.

Shut down the client

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

Unlike other LaunchDarkly SDKs, the Node.js (server-side) SDK does not automatically send pending analytics events to LaunchDarkly when it shuts down. To send analytics events, you first need to call flush.

Supported features

This SDK supports the following features:

• Anonymous contexts and users
• Big segments
• Bootstrapping
• Configuration, including
  • Application metadata configuration
  • Migration configuration
  • Service endpoint configuration
• Context configuration
• Data saving mode
• Evaluating flags
• Flag evaluation reasons
• Flushing events
• Getting all flags
• Hooks
• Identifying and changing contexts
• Logging configuration
• Migrations
• Observability
• Offline mode
• OpenTelemetry
• Private attributes
• Reading flags from a file
• Relay Proxy configuration
  • Using proxy mode
  • Using daemon mode
• Secure mode
• Sending custom events
• Service endpoint configuration
• Shutting down
• Storing data
• Subscribing to flag changes
• Test data sources
• Web proxy configuration