{"id":11226,"library":"launchdarkly-js-client-sdk","title":"LaunchDarkly JavaScript Client SDK (Legacy)","description":"The `launchdarkly-js-client-sdk` package provides client-side feature flag management for JavaScript applications running in web browsers. It allows developers to control features remotely without redeploying code, enabling practices like A/B testing, gradual rollouts, and kill switches. This specific package is currently at version 3.9.1 but is officially deprecated. All future development and releases are now happening under the `@launchdarkly/js-client-sdk` monorepo package. It leverages the 'Client-side ID' for authentication and requires flags to be explicitly made available to client-side SDKs. Release cadence was previously frequent for this package, but it is now in maintenance mode, with new features directed to the new package. Its primary differentiator is robust feature flag management with detailed event tracking and a strong focus on enterprise features, often used in conjunction with React through the `react-client-sdk` addon.","status":"deprecated","version":"3.9.1","language":"javascript","source_language":"en","source_url":"git://github.com/launchdarkly/js-client-sdk","tags":["javascript","launchdarkly","analytics","client","typescript"],"install":[{"cmd":"npm install launchdarkly-js-client-sdk","lang":"bash","label":"npm"},{"cmd":"yarn add launchdarkly-js-client-sdk","lang":"bash","label":"yarn"},{"cmd":"pnpm add launchdarkly-js-client-sdk","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const initialize = require('launchdarkly-js-client-sdk').initialize;","symbol":"initialize","correct":"import { initialize } from 'launchdarkly-js-client-sdk';"},{"note":"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.","wrong":"import LDClient from 'launchdarkly-js-client-sdk';","symbol":"LDClient","correct":"import { LDClient } from 'launchdarkly-js-client-sdk';"},{"note":"The `LDUser` interface defines the structure for user context objects passed during initialization and for flag evaluations. It's a named type export.","wrong":"import { User } from 'launchdarkly-js-client-sdk';","symbol":"LDUser","correct":"import { LDUser } from 'launchdarkly-js-client-sdk';"}],"quickstart":{"code":"import { initialize, LDUser, LDClient, LDOptions } from 'launchdarkly-js-client-sdk';\n\n// Replace with your actual Client-side ID from LaunchDarkly project settings\nconst LAUNCHDARKLY_CLIENT_SIDE_ID = process.env.LAUNCHDARKLY_CLIENT_SIDE_ID ?? 'YOUR_CLIENT_SIDE_ID';\n\n// Define a user context. The 'key' is mandatory.\nconst user: LDUser = {\n  key: 'example-user-key',\n  name: 'Example User',\n  email: 'user@example.com',\n  custom: {\n    region: 'us-west'\n  }\n};\n\n// Define SDK options (optional, here enabling debug logging)\nconst options: LDOptions = {\n  debug: true,\n};\n\n// Initialize the LaunchDarkly client\nconst ldClient: LDClient = initialize(LAUNCHDARKLY_CLIENT_SIDE_ID, user, options);\n\nldClient.on('ready', () => {\n  console.log('LaunchDarkly client is ready!');\n\n  // Evaluate a boolean feature flag with a default value of `false`\n  const showNewFeature = ldClient.variation('new-feature-flag', false);\n\n  if (showNewFeature) {\n    console.log('The new feature is ENABLED for this user!');\n  } else {\n    console.log('The new feature is DISABLED for this user.');\n  }\n\n  // Track a custom event for analytics\n  ldClient.track('button-click', { buttonId: 'submit-form' });\n});\n\nldClient.on('failed', (error) => {\n  console.error('LaunchDarkly initialization failed:', error);\n});\n\n// In a real application, you might export ldClient or make it globally available\n// for other parts of your application to use.","lang":"typescript","description":"Initializes the LaunchDarkly client for a given user, evaluates a boolean feature flag, and tracks a custom event, logging results to the console."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.9.1"},{"fix":"Verify that you are using the correct 'Client-side ID' found in your LaunchDarkly project's environment settings. It typically starts with '5...'.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Check the settings for any feature flags you intend to use with this SDK and ensure the client-side availability option is enabled.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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'.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.3.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Incorrect Client-side ID, network connectivity issues, or firewall blocking access to LaunchDarkly servers.","error":"LaunchDarkly client did not initialize. Please check your SDK key and network connection."},{"fix":"Add a `Promise` polyfill (e.g., from `core-js` or `es6-promise`) to your application bundle to ensure compatibility with older browsers.","cause":"The browser environment does not natively support the `Promise` object, and no polyfill has been included.","error":"ReferenceError: Promise is not defined"},{"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.","cause":"Attempting to call `variation` on an `ldClient` instance that has not yet completed initialization or is undefined due to initialization failure.","error":"TypeError: ldClient.variation is not a function"}],"ecosystem":"npm"}