• Home
  • Integrations
  • SDKs
  • Guides
  • API docs
No results for ""
EXPAND ALL

EDIT ON GITHUB

Node.js SDK reference (client-side)

Read time: 2 minutes
Last edited: Sep 24, 2021

Overview

This reference guide documents all of the methods available in the client-side Node.js SDK, and explains in detail how these methods work. LaunchDarkly's SDKs are open source. To learn more, read Client-Side Node.js SDK GitHub repository. The online API docs contain the programmatic definitions of every type and method. You can also try this SDK out by cloning and running a sample application.

For use in desktop or Node-enabled device applications only

This SDK is intended for use in single-user desktop or Node-enabled device applications. If you have a Node.js application and are looking to set up LaunchDarkly on the server-side, head to our Node.js SDK reference. If you are using Electron, there is an Electron SDK more specifically designed for that environment.

To learn more, read client-side and server-side SDKs.

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.

Getting started

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

The first step is to install the LaunchDarkly SDK as a dependency in your application using your application's dependency manager.

Here's how:

1npm install --save launchdarkly-node-client-sdk

Next, import the LaunchDarkly client in your application code:

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

Once the SDK is installed and imported, Create a single, shared instance of LdClient. This authorizes your application to connect to LaunchDarkly and retrieve flag values for your application and environment. To create a client instance, you need your environment's mobile key, available in the Projects tab of your account settings page. Be sure to use a client-side ID. Never embed a server-side SDK key into a client-side application. Client-side IDs are not secret and you can expose them in your client-side code without risk.

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 a basic example showing how to initialize the client:

1const user = {
2 key: "aa0ceb"
3};
4
5const client = LaunchDarkly.initialize('YOUR_CLIENT_SIDE_ID', user);

The client will emit a ready event when it has been initialized. You can also use the waitForInitialization() method, which returns a Promise. Once it has been initialized, you can safely call variation to access your feature flags. The ready event is only emitted 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:

1client.on('ready', () => {
2 console.log("It's now safe to request feature flags");
3
4 const showFeature = client.variation("YOUR_FEATURE_KEY", false);
5
6 if (showFeature) {
7 ...
8 } else {
9 ...
10 }
11});
Streaming updates

The SDK does not subscribe to streaming real-time updates automatically when it is initialized. Setting the streaming option to true in the client configuration causes the SDK to open a streaming connection to LaunchDarkly and receive live feature flag updates. You can also specify an event handler with client.on('change') to be notified immediately when a flag changes.

Making feature flags available to this SDK

You must make feature flags available to client-side SDKs before the flags can be evaluated. If you evaluate a feature flag that is not available, you receive the default value for that flag. If you want a project's flags to be made available to this SDK by default, check the SDKs using Client-side ID checkbox in your project Settings.

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

Supported features

This SDK supports the following features: