Node.js SDK reference (server-side)

Overview

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.

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.

Getting started

After you complete the Getting Started process, follow these instructions to start using the LaunchDarkly SDK in your Node.js application.

First, 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 launchdarkly-node-server-sdk or ldclient-node
COPY

Next, import the LaunchDarkly client in your application code:

const ld = require('@launchdarkly/node-server-sdk');
COPY

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:

const client = ld.init('sdk-key-123abc');
COPY

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 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:

const context = {
   "kind": 'user',
   "key": 'user-key-123abc',
   "name": 'Sandy'
};
client.once('ready', () => {
  client.variation('flag-key-123abc', context, false,
    (err, showFeature) => {
      if (showFeature) {
        // application code to show the feature
      } else {
        // the code to run if the feature is off
      }
    });
});
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. 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('flag-key-123abc', context, false).then((value) => {
  // application code
});
// Using "await" instead, within an async function
const value = await client.variation('flag-key-123abc', context, false);
COPY

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
}
COPY

allFlagsState and flush also return a Promise.

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
• Evaluating flags
• Flag evaluation reasons
• Flushing events
• Getting all flags
• Identifying and changing contexts
• Logging configuration
• Offline mode
• 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
• User and context configuration
• Web proxy configuration