LaunchDarkly JavaScript Client SDK (Legacy)

Common errors

• LaunchDarkly client did not initialize. Please check your SDK key and network connection.

  cause Incorrect Client-side ID, network connectivity issues, or firewall blocking access to LaunchDarkly servers.
  fix Double-check the provided Client-side ID against your LaunchDarkly project settings. Ensure your client device has active internet access and is not being blocked by a firewall or proxy from reaching LaunchDarkly endpoints.

• ReferenceError: Promise is not defined

  cause The browser environment does not natively support the `Promise` object, and no polyfill has been included.
  fix Add a `Promise` polyfill (e.g., from `core-js` or `es6-promise`) to your application bundle to ensure compatibility with older browsers.

• TypeError: ldClient.variation is not a function

  cause Attempting to call `variation` on an `ldClient` instance that has not yet completed initialization or is undefined due to initialization failure.
  fix Ensure you call `ldClient.variation` only after the `ready` event fires or `waitForInitialization()` resolves, indicating the client is ready to provide flag values. Handle potential initialization failures gracefully.

Warnings

• breaking This `launchdarkly-js-client-sdk` package is officially deprecated. All future development, bug fixes, and new features will be released under the new monorepo package `@launchdarkly/js-client-sdk`. Users are strongly encouraged to migrate.
  Fix: Migrate your project to use the `@launchdarkly/js-client-sdk` package. Refer to the official LaunchDarkly documentation and migration guides for the new package.
• gotcha The SDK requires a 'Client-side ID' from your LaunchDarkly account settings, not the 'SDK key' or 'Mobile key'. Using the incorrect key will prevent the client from initializing and fetching flags.
  Fix: Verify that you are using the correct 'Client-side ID' found in your LaunchDarkly project's environment settings. It typically starts with '5...'.
• gotcha For any feature flag to be accessible in the client-side SDK, the 'Make this flag available to client-side SDKs' checkbox must be enabled on the flag's settings page in the LaunchDarkly dashboard.
  Fix: Check the settings for any feature flags you intend to use with this SDK and ensure the client-side availability option is enabled.
• gotcha Older browser environments may lack native support for features like `Promise`, `EventSource`, or `document.querySelectorAll()`, which are used by the SDK. This can lead to runtime errors or silent failures.
  Fix: Include appropriate polyfills (e.g., `core-js`, `whatwg-fetch`) in your application bundle if you need to support older browsers. Consult the LaunchDarkly documentation on 'JS SDK requirements and polyfills'.
• gotcha The `waitForInitialization` method, if called without a timeout, will await indefinitely if the client fails to initialize (e.g., due to network issues or incorrect configuration) without an explicit error handler or rejection.
  Fix: Consider adding an optional timeout parameter to `waitForInitialization` (e.g., `ldClient.waitForInitialization(5000)`) to ensure that the promise eventually resolves or rejects, preventing indefinite blocking.

Install

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

Imports

• initialize
  wrong:

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

  correct:

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

  The `initialize` function is the primary entry point for the SDK, returning an `LDClient` instance. While CommonJS `require` works, ESM `import` is the recommended modern approach for browser-based JavaScript.
• LDClient
  wrong:

  import LDClient from 'launchdarkly-js-client-sdk';

  correct:

  import { LDClient } from 'launchdarkly-js-client-sdk';

  The `LDClient` class (or its type) is returned by the `initialize` function. It's a named export, not a default export. You typically obtain an instance from `initialize` rather than creating it directly.
• LDUser
  wrong:

  import { User } from 'launchdarkly-js-client-sdk';

  correct:

  import { LDUser } from 'launchdarkly-js-client-sdk';

  The `LDUser` interface defines the structure for user context objects passed during initialization and for flag evaluations. It's a named type export.

Quickstart

Initializes the LaunchDarkly client for a given user, evaluates a boolean feature flag, and tracks a custom event, logging results to the console.

import { initialize, LDUser, LDClient, LDOptions } from 'launchdarkly-js-client-sdk';

// Replace with your actual Client-side ID from LaunchDarkly project settings
const LAUNCHDARKLY_CLIENT_SIDE_ID = process.env.LAUNCHDARKLY_CLIENT_SIDE_ID ?? 'YOUR_CLIENT_SIDE_ID';

// Define a user context. The 'key' is mandatory.
const user: LDUser = {
  key: 'example-user-key',
  name: 'Example User',
  email: 'user@example.com',
  custom: {
    region: 'us-west'
  }
};

// Define SDK options (optional, here enabling debug logging)
const options: LDOptions = {
  debug: true,
};

// Initialize the LaunchDarkly client
const ldClient: LDClient = initialize(LAUNCHDARKLY_CLIENT_SIDE_ID, user, options);

ldClient.on('ready', () => {
  console.log('LaunchDarkly client is ready!');

  // Evaluate a boolean feature flag with a default value of `false`
  const showNewFeature = ldClient.variation('new-feature-flag', false);

  if (showNewFeature) {
    console.log('The new feature is ENABLED for this user!');
  } else {
    console.log('The new feature is DISABLED for this user.');
  }

  // Track a custom event for analytics
  ldClient.track('button-click', { buttonId: 'submit-form' });
});

ldClient.on('failed', (error) => {
  console.error('LaunchDarkly initialization failed:', error);
});

// In a real application, you might export ldClient or make it globally available
// for other parts of your application to use.