{"id":11227,"library":"launchdarkly-js-sdk-common","title":"LaunchDarkly JavaScript SDK Common Components","description":"This package (`launchdarkly-js-sdk-common`) serves as the foundational core for all client-side JavaScript-based LaunchDarkly SDKs, including the browser, React, client-side Node, and Electron SDKs. It provides the essential, platform-agnostic implementation components, such as the `initialize` function used to create the basic client object and shared TypeScript definitions. Crucially, application developers should not directly reference or import from this package; it is an internal dependency for other LaunchDarkly SDKs. The current stable version is 5.8.0, with minor releases occurring frequently, often monthly or bi-monthly, introducing new features and bug fixes to support broader LaunchDarkly platform capabilities. Its key differentiator is providing a consistent, shared codebase to reduce duplication and ensure behavioral parity across various JavaScript environments for the LaunchDarkly ecosystem.","status":"active","version":"5.8.0","language":"javascript","source_language":"en","source_url":"git://github.com/launchdarkly/js-sdk-common","tags":["javascript","typescript"],"install":[{"cmd":"npm install launchdarkly-js-sdk-common","lang":"bash","label":"npm"},{"cmd":"yarn add launchdarkly-js-sdk-common","lang":"bash","label":"yarn"},{"cmd":"pnpm add launchdarkly-js-sdk-common","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `initialize` function is the core entry point for creating a client object, intended for internal use by higher-level LaunchDarkly SDKs, not direct application consumption. Using `require()` may lead to issues if the package is ESM-only in certain environments or versions.","wrong":"const { initialize } = require('launchdarkly-js-sdk-common');","symbol":"initialize","correct":"import { initialize } from 'launchdarkly-js-sdk-common';"},{"note":"This type defines the core client interface. When importing types in TypeScript, always use `import type` to prevent bundling issues and ensure it's treated as a type-only import. This interface is often extended by specific SDKs to add public methods.","wrong":"import { LDClient } from 'launchdarkly-js-sdk-common';","symbol":"LDClient","correct":"import type { LDClient } from 'launchdarkly-js-sdk-common';"},{"note":"This type defines the common configuration options for the SDK client. Use `import type` for type-only imports in TypeScript projects. Specific SDKs may extend these options.","wrong":"import { LDOptions } from 'launchdarkly-js-sdk-common';","symbol":"LDOptions","correct":"import type { LDOptions } from 'launchdarkly-js-sdk-common';"}],"quickstart":{"code":"import { initialize, LDClient, LDOptions } from 'launchdarkly-js-sdk-common';\n\n// This is an example of how a higher-level LaunchDarkly SDK (e.g., js-client-sdk)\n// might internally use launchdarkly-js-sdk-common to create a client instance.\n// Application code should *not* directly use this package.\n\n// Define a minimal \"platform\" object that provides environment-specific capabilities\nconst browserPlatform = {\n  // Example placeholder for browser-specific functions\n  getCurrentUrl: () => typeof window !== 'undefined' ? window.location.href : 'about:blank',\n  sendEvent: (event: any) => { console.log('Sending event (browser mock):', event); },\n  // ... other browser-specific implementations like localStorage, network requests, etc.\n};\n\n// Define some basic SDK options\nconst sdkOptions: LDOptions = {\n  // A placeholder SDK key, in a real scenario this would come from env or config\n  sdkKey: process.env.LAUNCHDARKLY_SDK_KEY ?? 'your-sdk-key',\n  bootstrap: {}, // No initial flags for this example\n  streaming: true,\n  // More options as needed by the specific SDK\n};\n\nlet client: LDClient | undefined;\n\ntry {\n  // The 'initialize' function from common is called by specific SDKs\n  // with their platform implementation to create the core client.\n  client = initialize(sdkOptions, browserPlatform);\n\n  client.on('ready', () => {\n    console.log('LaunchDarkly common client is ready internally.');\n    const userContext = { kind: 'user', key: 'test-user-123' };\n    client?.identify(userContext); // Internal identify call\n\n    // Simulate getting a flag value (would be done by the higher-level SDK)\n    const flagValue = client?.variation('my-test-feature', false);\n    console.log(`Internal variation for 'my-test-feature': ${flagValue}`);\n\n    // Clean up\n    client?.close();\n  });\n\n  client.on('failed', (err: any) => {\n    console.error('LaunchDarkly common client failed to initialize:', err);\n  });\n\n  console.log('Attempting to initialize LaunchDarkly common client...');\n} catch (error) {\n  console.error('Error during common client initialization:', error);\n}\n","lang":"typescript","description":"This TypeScript example illustrates how a higher-level LaunchDarkly SDK (like `js-client-sdk`) internally utilizes `launchdarkly-js-sdk-common`'s `initialize` function with a platform object and basic options to create a core `LDClient` instance, and demonstrates its internal event handling and variation fetching."},"warnings":[{"fix":"Use a specific LaunchDarkly SDK package relevant to your environment (e.g., `launchdarkly-js-client-sdk` for browsers or Node.js, `launchdarkly-react-client-sdk` for React applications) rather than directly importing from `launchdarkly-js-sdk-common`.","message":"This package (`launchdarkly-js-sdk-common`) is an internal dependency for other LaunchDarkly SDKs (e.g., `launchdarkly-js-client-sdk`, `launchdarkly-react-client-sdk`). Direct consumption by application code is explicitly discouraged and may lead to unexpected behavior or future breaking changes without warning.","severity":"gotcha","affected_versions":"*"},{"fix":"Ensure your environment provides stable streaming connectivity or configure specific SDKs to use polling if streaming is not viable. Consult the documentation for your specific LaunchDarkly SDK for alternative connection methods.","message":"The HTTP fallback ping mechanism was removed in version 5.1.0. This change might affect environments where streaming connections were unstable and previously relied on this fallback for basic flag updates.","severity":"breaking","affected_versions":">=5.1.0"},{"fix":"Review any custom event processing or data pipelines that consume LaunchDarkly events to ensure compatibility with the updated event structure and redaction policies.","message":"As of version 5.1.0, anonymous attributes are redacted within feature events, and contexts are always inlined for feature events. This changes the structure and content of event data sent to LaunchDarkly, potentially impacting event processing or custom integrations that rely on the exact previous event structure.","severity":"breaking","affected_versions":">=5.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure the package is installed (`npm install launchdarkly-js-sdk-common`). For modern JavaScript, prefer `import` statements. Most importantly, ensure you are using a public-facing LaunchDarkly SDK, which will handle its internal dependency on `launchdarkly-js-sdk-common`.","cause":"Attempting to `require()` the package in an ESM-only context or missing package installation. Also, often occurs if trying to use this internal package directly when it's not exposed as a top-level module in your specific environment.","error":"Error: Cannot find module 'launchdarkly-js-sdk-common'"},{"fix":"Ensure `initialize` is imported as a named export: `import { initialize } from 'launchdarkly-js-sdk-common';`. Remember that this function is primarily for internal SDK use and not typically invoked directly by application code.","cause":"Incorrectly importing `initialize` (e.g., as a default import when it's a named export) or trying to call `initialize` from a `require()` statement in an ESM-only module. This error is also common if directly using this internal package outside of its intended SDK context.","error":"TypeError: initialize is not a function"},{"fix":"When using a concrete LaunchDarkly client instance obtained from a specific SDK (e.g., `launchdarkly-js-client-sdk`), ensure you cast or type the client object to that SDK's specific client type (e.g., `LDBrowserClient`) to correctly access all its public API methods.","cause":"The `LDClient` interface from `launchdarkly-js-sdk-common` provides core client definitions, but specific public methods like `variation` are often added by higher-level, environment-specific SDKs that extend `LDClient`.","error":"Property 'variation' does not exist on type 'LDClient'"}],"ecosystem":"npm"}