LaunchDarkly Node.js Client-Side SDK

Common errors

• TypeError: LaunchDarkly.initialize is not a function

  cause 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.

  cause 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.

  cause 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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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`.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install launchdarkly-node-client-sdk npm
• yarn add launchdarkly-node-client-sdk yarn
• pnpm add launchdarkly-node-client-sdk pnpm

Imports

• initialize
  wrong:

  const initialize = require('launchdarkly-node-client-sdk').initialize;

  correct:

  import { initialize } from 'launchdarkly-node-client-sdk';

  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.

Quickstart

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();