Node.js SDK reference (server-side)
Read time: 6 minutes
Last edited: Jul 26, 2023
Version 8 of the Node.js (server-side) SDK has been re-written in TypeScript, and the GitHub repository and package names have been updated. To learn more about upgrading, read Node.js (server-side) 7.x to 8.0 migration guide.
Version 7 of the Node.js (server-side) SDK replaces users with contexts. A context is a generalized way of referring to the people, services, machines, or other resources that encounter feature flags in your product. Contexts replace another data object in LaunchDarkly: "users." To learn more about upgrading, read Node.js (server-side) 6.x to 7.0 migration guide and Best practices for upgrading users to contexts.
Code samples on this page are from the three most recent SDK versions where they differ.
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.
LaunchDarkly's SDKs are open source. In addition to this reference guide, we provide source, API reference documentation, and sample applications:
Resource | Location |
---|---|
SDK API documentation | SDK API docs |
GitHub repository | node-server-sdk |
Sample applications | Node.js (server-side) Node.js (server-side), TypeScript Node.js (server-side) with bootstrapping OpenFeature Node.js (server-side) |
Published module | npm |
This SDK is intended for use in multi-user Node.js server applications. If you want to set up LaunchDarkly in JavaScript in a browser environment, read the JavaScript SDK reference. If you're creating a client-side Node application, read the Node.js SDK reference (client-side). If you're creating a desktop application in Electron, read the Electron SDK reference.
To learn more about LaunchDarkly's different SDK types, read Client-side and server-side SDKs.
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
Next, import the LaunchDarkly client in your application code:
const ld = require('@launchdarkly/node-server-sdk');
The Node.js (server-side) SDK uses an SDK key. Your environment's SDK key is available in the Projects tab of your Account settings page. To learn more about key types, read Keys.
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');
It's important to make LDClient
a singleton for each LaunchDarkly project. The client instance maintains internal state that allows us to serve feature flags without making any remote requests. Do not instantiate a new client with every request.
If you have multiple LaunchDarkly projects, you can create one LDClient
for each. In this situation, the clients operate independently. For example, they do not share a single connection to LaunchDarkly.
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}});});
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 Promiseclient.variation('flag-key-123abc', context, false).then((value) => {// application code});// Using "await" instead, within an async functionconst value = await client.variation('flag-key-123abc', context, false);
There is also an alternative to the ready
event:
// Using .then() and .catch() to add success and error handlers to a Promiseclient.waitForInitialization().then((client) => {// initialization complete}).catch((err) => {// initialization failed});// Using "await" instead, within an async functiontry {await client.waitForInitialization();// Initialization complete} catch (err) {// Initialization failed}
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
- 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