Node.js SDK reference (client-side)

Overview

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

This SDK is closely related to the browser JavaScript SDK and has almost exactly the same API, but does not have any browser-specific functionality and adds several features specific to Node.

Get started

After you complete the Get started process, follow these instructions to start using the LaunchDarkly SDK in your Node.js code:

• Install the SDK
• Initialize the client
• Subscribe to flag changes

Install the SDK

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

Here's how:

npm install launchdarkly-node-client-sdk
COPY

Next, import the LaunchDarkly client in your application code:

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

Initialize the client

After you install and import the SDK, create a single, shared instance of LDClient. To create a client instance, you need your environment's client-side ID. This authorizes your application to connect to a particular environment within LaunchDarkly.

Feature flag targeting and rollouts are determined by the active context, which describes the end user using your application. You must pass a context to the SDK during initialization before requesting any feature flags with variation. Failure to pass a valid context to the SDK during initialization will result in an error.

When you initialize the client, use the waitForInitialization() method to determine if the client successfully initializes. The waitForInitialization() method takes a timeout, which we recommend setting to five seconds or fewer. If you use a large timeout and await it, then any network delays will cause your application to wait a long time before continuing execution.

Here's how to initialize the client:

const context = {
  kind: 'user',
  key: 'user-key-123abc'
};
const client = LaunchDarkly.initialize('client-side-id-123abc', context);
try {
  await client.waitForInitialization(5);
  // initialization succeeded, flag values are now available
} catch (err) {
  // initialization failed or did not complete before timeout
}
COPY

As an alternative to the waitForInitialization() call, you can use event listeners instead. The client emits the event "initialized" to indicate success, and "failed" to indicate failure. The client also emits a "ready" event when it has finished starting up, regardless of whether it successfully connected to LaunchDarkly or encountered an error. In a production application, your calls to client.variation would normally not be inside of this event handler.

To use event listeners:

client.on('initialized', () => {
  // initialization succeeded, flag values are now available
  const flagValue = client.variation('flag-key-123abc', false);
  // etc.
});
COPY

When you initialize the client, you can optionally provide configuration options. To learn how, read Configuration. To learn more about the specific configuration options available in this SDK, read LDOptions.

After you have initialized the client, you can safely call variation to access your feature flags.

Subscribe to flag changes

The SDK does not subscribe to streaming real-time updates automatically when you initialize it.

In some cases, streaming may not be necessary. For example, if you reload your entire application on each update, you will get all the flag values again when the client is re-initialized. If this is your use case, you should leave the streaming value undefined, which is the default.

In other cases, streaming may be required. Subscribing to streaming is the only way to receive real-time updates. If you determine that streaming is necessary for your application, there are two ways to subscribe to streaming:

• Explicitly subscribe to streaming: If you set the streaming configuration option to true, the client will always attempt to maintain a streaming connection.
• Register a change listener: If you specify an event handler with client.on('change') the client will open a streaming connection. It will close this streaming connection when you unsubscribe from the event, for example by calling client.off('change'). Because opening and closing streaming connections can be expensive, you should explicitly enable streaming if your application frequently starts and stops listening to changes.

Shut down the client

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

Supported features

This SDK supports the following features:

• Anonymous contexts and users
• Bootstrapping
• Configuration, including
  • Application metadata configuration
  • Service endpoint configuration
• Context configuration
• Evaluating flags
• Flag evaluation reasons
• Flushing events
• Getting all flags
• Identifying and changing contexts
• Logging configuration
• Private attributes
• Relay Proxy configuration, using proxy mode
• Secure mode
• Sending custom events
• Shutting down
• Subscribing to flag changes