• HOME
  • INTEGRATIONS
  • SDKS
  • GUIDES
  • API DOCS
No results for ""
EXPAND ALL
launchdarkly.com

EDIT ON GITHUB

Node.js SDK reference (client-side)

Read time: 2 minutes
Last edited: Jun 18, 2021

This reference guide documents all of the methods available in the client-side Node.js SDK, and explains in detail how these methods work. If you want to dig even deeper, our 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. Additionally you can clone and run a sample application using this SDK.

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

Building on top of our Getting Started guide, the following steps will get you started with 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.

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

Next you should import the LaunchDarkly client in your application code.

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

Once the SDK is installed and imported, you'll want to create a single, shared instance of the LaunchDarkly client. To create a client instance, you need your environment's client-side ID (available on your account settings page). Client-side IDs are not secret. You can expose them in your client-side code with no 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 ldClient = 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. (Note that the ready event is only emitted once, when the client first initializes. In a production application, your calls to ldClient.variation would normally not be inside of this event handler.)

1ldClient.on('ready', () => {
2 console.log("It's now safe to request feature flags");
3
4 const showFeature = ldClient.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 ldClient.on('change') to be notified immediately when a flag changes.

Making feature flags available to the client-side SDK

Feature flags must be marked available to the client-side SDK (see your feature flag's settings page) before they can be used in variation calls on the front-end. If you request a feature flag that is not available, you'll receive the default value for that flag. If you always want flags marked as available to the client-side SDK by default, you can check the "Make new flags available to the client-side (JavaScript) SDK by default" in your project settings.

Lastly, when your application is about to terminate, shut down ldClient. This ensures that the client releases any resources it is using, and that any pending analytics events are delivered to LaunchDarkly. If your application quits without this shutdown step, you may not see your requests and users on the dashboard, because they are derived from analytics events. This is something you only need to do once.

1ldClient.close(() => {
2 console.log('Client has been closed');
3 process.exit(0);
4});

Supported features

This SDK supports the following features: