{"id":15671,"library":"launchdarkly-node-client-sdk","title":"LaunchDarkly Node.js Client-Side SDK","description":"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.","status":"active","version":"3.3.1","language":"javascript","source_language":"en","source_url":"git://github.com/launchdarkly/node-client-sdk","tags":["javascript","launchdarkly","analytics","client","typescript"],"install":[{"cmd":"npm install launchdarkly-node-client-sdk","lang":"bash","label":"npm"},{"cmd":"yarn add launchdarkly-node-client-sdk","lang":"bash","label":"yarn"},{"cmd":"pnpm add launchdarkly-node-client-sdk","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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');`","wrong":"const initialize = require('launchdarkly-node-client-sdk').initialize;","symbol":"initialize","correct":"import { initialize } from 'launchdarkly-node-client-sdk';"},{"note":"Type definition for the context object used in flag evaluations. Mandatory since v3.0.0.","symbol":"LDContext","correct":"import { LDContext } from 'launchdarkly-node-client-sdk';"},{"note":"Type definition for the SDK client instance returned by `initialize()`. Useful for type hinting.","symbol":"LDClient","correct":"import { LDClient } from 'launchdarkly-node-client-sdk';"}],"quickstart":{"code":"import { initialize, LDContext, LDClient } from 'launchdarkly-node-client-sdk';\n\nconst clientSideId = process.env.LAUNCHDARKLY_CLIENT_SIDE_ID ?? 'YOUR_CLIENT_SIDE_ID_HERE';\n\nif (clientSideId === 'YOUR_CLIENT_SIDE_ID_HERE') {\n  console.warn('Please set the LAUNCHDARKLY_CLIENT_SIDE_ID environment variable or replace the placeholder.');\n}\n\nasync function runFeatureFlagExample() {\n  const context: LDContext = {\n    kind: 'user',\n    key: 'example-user-key',\n    name: 'Example User',\n    // You can add custom attributes here, e.g.:\n    // country: 'us',\n    // anonymous: true,\n  };\n\n  console.log('Initializing LaunchDarkly client...');\n  const client: LDClient = initialize(clientSideId, context);\n\n  try {\n    // Wait for the client to connect to LaunchDarkly. A timeout is highly recommended.\n    // e.g., await client.waitForInitialization(5000);\n    await client.waitForInitialization();\n    console.log('LaunchDarkly client initialized.');\n\n    // Evaluate a feature flag\n    const showNewFeature = client.variation('new-feature', false); // 'new-feature' is flag key, false is default value\n    console.log(`Feature flag 'new-feature' is ${showNewFeature ? 'ON' : 'OFF'}.`);\n\n    const welcomeMessage = client.variation('welcome-message', 'Hello, user!');\n    console.log(`Welcome message: \"${welcomeMessage}\"`);\n\n    // You can also track custom events\n    client.track('button-click', context, { buttonId: 'primary-cta' });\n    console.log('Custom event \"button-click\" tracked.');\n\n  } catch (error) {\n    console.error('Failed to initialize LaunchDarkly client or evaluate flags:', error);\n  } finally {\n    // Always close the client when done to ensure all events are sent and connections are closed\n    console.log('Closing LaunchDarkly client...');\n    client.close();\n    console.log('Client closed.');\n  }\n}\n\nrunFeatureFlagExample();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=3.0.0"},{"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`.","message":"This 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Prior 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.","severity":"gotcha","affected_versions":">=3.2.0"},{"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.","message":"Version 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.","severity":"gotcha","affected_versions":">=3.0.2"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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()`.","cause":"Incorrect import statement for ES Modules or CommonJS.","error":"TypeError: LaunchDarkly.initialize is not a function"},{"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.","cause":"A `variation()` call was made before the SDK had successfully initialized and connected to LaunchDarkly.","error":"LaunchDarkly SDK is not initialized. Flag 'some-flag' will return default value."},{"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.","cause":"A server-side SDK key was used instead of a client-side SDK key during initialization.","error":"LaunchDarkly: The SDK key you provided does not appear to be a client-side SDK key."}],"ecosystem":"npm"}