Registry / crm-productivity / launchdarkly-node-client-sdk

launchdarkly-node-client-sdk

JSON →
library3.3.1jsnpmunverified

This package provides the LaunchDarkly Client-Side SDK for Node.js environments, specifically designed for applications deployed to an end-user, such as desktop apps or smart devices, rather than multi-user server-side systems. It enables developers to integrate feature flagging capabilities into their Node.js client applications, allowing for controlled feature rollouts, A/B testing, and dynamic configuration. The current stable version is 3.3.1. The SDK maintains an active release cadence, with updates typically every few months, addressing bug fixes, performance improvements, and new features like client-side prerequisite events and enhanced error handling. A key differentiator is its explicit focus on single-user contexts, contrasting with the separate server-side SDK for multi-user applications, and its evolution to support custom contexts over the older 'users' concept in version 3.0.0.

npm install launchdarkly-node-client-sdk
INSTALL
IMPORT
SIG · LAUNCHDARKLY-NODE-
L
launchdarkly-node-client-sdk
crm-productivityjavascriptv3.3.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

initialize
import { initialize } from 'launchdarkly-node-client-sdk';
const initialize = require('launchdarkly-node-client-sdk').initialize;
The primary function to create an SDK client instance. This is an ESM named export. For CJS, use `require('pkg').initialize` or `const { initialize } = require('pkg');`
LDContext
import { LDContext } from 'launchdarkly-node-client-sdk';
Type definition for the context object used in flag evaluations. Mandatory since v3.0.0.
LDClient
import { LDClient } from 'launchdarkly-node-client-sdk';
Type definition for the SDK client instance returned by `initialize()`. Useful for type hinting.

Demonstrates how to initialize the LaunchDarkly client with a context, wait for initialization, evaluate a boolean and string feature flag, and track a custom event.

import { initialize, LDContext, LDClient } from 'launchdarkly-node-client-sdk'; const clientSideId = process.env.LAUNCHDARKLY_CLIENT_SIDE_ID ?? 'YOUR_CLIENT_SIDE_ID_HERE'; if (clientSideId === 'YOUR_CLIENT_SIDE_ID_HERE') { console.warn('Please set the LAUNCHDARKLY_CLIENT_SIDE_ID environment variable or replace the placeholder.'); } async function runFeatureFlagExample() { const context: LDContext = { kind: 'user', key: 'example-user-key', name: 'Example User', // You can add custom attributes here, e.g.: // country: 'us', // anonymous: true, }; console.log('Initializing LaunchDarkly client...'); const client: LDClient = initialize(clientSideId, context); try { // Wait for the client to connect to LaunchDarkly. A timeout is highly recommended. // e.g., await client.waitForInitialization(5000); await client.waitForInitialization(); console.log('LaunchDarkly client initialized.'); // Evaluate a feature flag const showNewFeature = client.variation('new-feature', false); // 'new-feature' is flag key, false is default value console.log(`Feature flag 'new-feature' is ${showNewFeature ? 'ON' : 'OFF'}.`); const welcomeMessage = client.variation('welcome-message', 'Hello, user!'); console.log(`Welcome message: "${welcomeMessage}"`); // You can also track custom events client.track('button-click', context, { buttonId: 'primary-cta' }); console.log('Custom event "button-click" tracked.'); } catch (error) { console.error('Failed to initialize LaunchDarkly client or evaluate flags:', error); } finally { // Always close the client when done to ensure all events are sent and connections are closed console.log('Closing LaunchDarkly client...'); client.close(); console.log('Client closed.'); } } runFeatureFlagExample();
Debug
Known issues
breakingVersion 3.0.0 introduced a breaking change by replacing the `user` concept with `context` (or `LDContext`). All flag evaluations and SDK interactions now require an `LDContext` object instead of a `user` object. Code written for v2.x will fail if still passing `user` objects.
fix
Refactor all `user` objects to conform to the `LDContext` interface. For single users, `context` has a `kind` attribute set to `'user'` and a `key` property. Consult the migration guide for a full list of changes.
affects: >=3.0.0
gotchaThis SDK (`launchdarkly-node-client-sdk`) is designed exclusively for client-side Node.js applications (e.g., desktop apps or IoT devices) where a single client instance serves a single user context. It is explicitly *not* intended for multi-user server-side applications. Using it in a server environment will lead to incorrect flag evaluations, performance issues, and potential data privacy concerns.
fix
For server-side Node.js applications, use `launchdarkly-node-server-sdk` instead. If you need a client-side SDK in a browser, use `launchdarkly-js-client-sdk`.
affects: All versions
gotchaPrior to v3.2.0, `waitForInitialization` would wait indefinitely if no timeout was specified. Since v3.2.0, you can now provide an optional timeout (e.g., `client.waitForInitialization(5000)`) which will reject the promise if initialization does not complete within the specified time. If no timeout is specified, it will still wait indefinitely.
fix
Consider adding a timeout to `waitForInitialization` to prevent your application from hanging indefinitely during SDK initialization failure or network issues. Recommended timeouts for client-side SDKs are 100-500ms.
affects: >=3.2.0
gotchaVersion 3.0.2 updated `LDContext` to allow the `key` property to be optional, specifically for anonymous contexts where a key can be generated. However, it is generally recommended to provide a specific `key` for better traceability, targeting, and consistency across sessions, unless an anonymous context with a generated key is explicitly desired.
fix
Prefer providing a unique `key` for your `LDContext` objects to ensure consistent user identification and accurate flag targeting, unless explicitly designing for anonymous users with generated keys.
affects: >=3.0.2
Errors
Common errors & fixes
TypeError: LaunchDarkly.initialize is not a function
Incorrect import statement for ES Modules or CommonJS.
fix
If using ES Modules (TypeScript/modern Node.js), use `import { initialize } from 'launchdarkly-node-client-sdk';`. If using CommonJS, use `const { initialize } = require('launchdarkly-node-client-sdk');` or `const LaunchDarkly = require('launchdarkly-node-client-sdk');` and then `LaunchDarkly.initialize()`.
LaunchDarkly SDK is not initialized. Flag 'some-flag' will return default value.
A `variation()` call was made before the SDK had successfully initialized and connected to LaunchDarkly.
fix
Ensure `await client.waitForInitialization()` (with an optional timeout) is called and resolved before attempting to evaluate feature flags. This guarantees the SDK has fetched flag configurations.
LaunchDarkly: The SDK key you provided does not appear to be a client-side SDK key.
A server-side SDK key was used instead of a client-side SDK key during initialization.
fix
Verify that you are using a *client-side* SDK key obtained from your LaunchDarkly project settings. Client-side keys are designed to be embedded in client applications and usually start with `mob-` or `client-`. Never use a server-side SDK key (which is a secret) in client-side code.
Upgrade
Version history
3.3.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
29 hits · last 30 days
node
26
OpenAI (training)
1
Resources
launchdarkly-node-client-sdk — npm install launchdarkly-node-client-sdk · libregistry