LaunchDarkly JavaScript SDK Common Components

Common errors

• Error: Cannot find module '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.
  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`.

• TypeError: initialize is not a function

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

• Property 'variation' does not exist on type 'LDClient'

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

Warnings

• gotcha 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.
  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`.
• breaking 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.
  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.
• breaking 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.
  Fix: Review any custom event processing or data pipelines that consume LaunchDarkly events to ensure compatibility with the updated event structure and redaction policies.

Install

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

Imports

• initialize
  wrong:

  const { initialize } = require('launchdarkly-js-sdk-common');

  correct:

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

  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.
• LDClient
  wrong:

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

  correct:

  import type { LDClient } from 'launchdarkly-js-sdk-common';

  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.
• LDOptions
  wrong:

  import { LDOptions } from 'launchdarkly-js-sdk-common';

  correct:

  import type { LDOptions } from 'launchdarkly-js-sdk-common';

  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.

Quickstart

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.

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

// This is an example of how a higher-level LaunchDarkly SDK (e.g., js-client-sdk)
// might internally use launchdarkly-js-sdk-common to create a client instance.
// Application code should *not* directly use this package.

// Define a minimal "platform" object that provides environment-specific capabilities
const browserPlatform = {
  // Example placeholder for browser-specific functions
  getCurrentUrl: () => typeof window !== 'undefined' ? window.location.href : 'about:blank',
  sendEvent: (event: any) => { console.log('Sending event (browser mock):', event); },
  // ... other browser-specific implementations like localStorage, network requests, etc.
};

// Define some basic SDK options
const sdkOptions: LDOptions = {
  // A placeholder SDK key, in a real scenario this would come from env or config
  sdkKey: process.env.LAUNCHDARKLY_SDK_KEY ?? 'your-sdk-key',
  bootstrap: {}, // No initial flags for this example
  streaming: true,
  // More options as needed by the specific SDK
};

let client: LDClient | undefined;

try {
  // The 'initialize' function from common is called by specific SDKs
  // with their platform implementation to create the core client.
  client = initialize(sdkOptions, browserPlatform);

  client.on('ready', () => {
    console.log('LaunchDarkly common client is ready internally.');
    const userContext = { kind: 'user', key: 'test-user-123' };
    client?.identify(userContext); // Internal identify call

    // Simulate getting a flag value (would be done by the higher-level SDK)
    const flagValue = client?.variation('my-test-feature', false);
    console.log(`Internal variation for 'my-test-feature': ${flagValue}`);

    // Clean up
    client?.close();
  });

  client.on('failed', (err: any) => {
    console.error('LaunchDarkly common client failed to initialize:', err);
  });

  console.log('Attempting to initialize LaunchDarkly common client...');
} catch (error) {
  console.error('Error during common client initialization:', error);
}