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.

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 code.

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

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.

To find and copy your LaunchDarkly client-side ID:

1. Navigate to the Account settings page.
2. Click the Projects tab.
3. Click the name of your project. The Environments tab appears.
4. Click the environment's client-side ID to copy it to your clipboard.

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

Here's how to initialize the client:

const context = {
  kind: 'user',
  key: 'user-key-123abc'
};
const client = LaunchDarkly.initialize('client-side-id-123abc', context);
COPY

The client emits a ready event when you have initialized it. You can also use the waitForInitialization() method, which returns a Promise. After you have initialized it, you can safely call variation to access your feature flags. The SDK emits the ready event only once, when the client first initializes. In a production application, your calls to client.variation would normally not be inside of this event handler.

To emit a ready event:

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

Shutting down

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
• Evaluating flags
• Flag evaluation reasons
• Flushing events
• Getting all flags
• Identifying and changing contexts
• Logging configuration
• Private attributes
• Relay Proxy configuration, using proxy mode
• Sending custom events
• Shutting down
• Subscribing to flag changes
• User and context configuration