JavaScript SDK reference

Overview

This topic documents how to get started with the client-side JavaScript SDK, and links to reference information on all of the supported features.

This SDK does two things:

• Makes feature flags available to your client-side (front-end) JavaScript code.
• Sends click, page view, and custom events from your front-end for A/B tests and analytics.

Browser support

The LaunchDarkly client-side JavaScript SDK can be used in all major browsers. However, not all browsers have built-in support for the standard APIs that it uses. Those APIs are Promise, EventSource, and querySelectorAll. The SDK always requires Promise, but the other two are optional depending on which SDK features you use.

The standard solution for ensuring that you will get the same functionality even in browsers that do not have native support for these features is to use polyfills. For a detailed description, and links to information about which browsers may require this, read JS SDK requirements and polyfills.

Additionally, the JavaScript SDK versions 3.0.0 and 3.1.0 use optional chaining. If you encounter an error related to optional chaining during transpiling, bundling, or running tests, updating to version 3.1.1 should resolve the error.

Get started

After you complete the Get started process, follow these instructions to start using the LaunchDarkly JavaScript SDK in your JavaScript code:

• Install the SDK
• Initialize the client
• Determine when the client is ready, using an event or promise
• Subscribe to flag changes
• Shut down the client when your application terminates

Install the SDK

The first step is to make the JavaScript SDK available as a dependency.

In most cases, making the JavaScript SDK available to your application or site requires running one of the following in your project:

npm install launchdarkly-js-client-sdk
COPY

If you are using a package manager and combining dependencies with your code using a tool such as Webpack, there are various ways to import the JavaScript SDK into your code.

Here are some examples in commonly used frameworks:

// Using require()
const LDClient = require('launchdarkly-js-client-sdk');
// Using ES2015 imports
import * as LDClient from 'launchdarkly-js-client-sdk';
// Using TypeScript imports
import * as LDClient from 'launchdarkly-js-client-sdk';
COPY

In earlier versions of the SDK, the package was named ldclient-js instead of launchdarkly-js-client-sdk.

A less common method to make the JavaScript SDK available is with a script tag.

<!-- recommended for production environments -->
<script src="path/to/ldclient.min.js"></script>
COPY

Initialize the client

To create a client instance, you need your LaunchDarkly environment's client-side ID. This authorizes your application to connect to a particular environment within LaunchDarkly.

We recommend that you templatize your client-side ID so that you can use the same initialization code when you switch between development, QA, and production environments.

Feature flag targeting and rollouts are determined by the end user viewing the page. You must pass a context, which describes this end user, to the SDK during initialization before you can request any feature flags. If you fail to pass a valid context to the SDK during initialization, you will receive a 400 error.

To initialize the client:

const context = {
  kind: 'user',
  key: 'context-key-123abc'
};
const client = LDClient.initialize('client-side-id-123abc', context);
COPY

When you initialize the client, you can optionally provide configuration options. To learn how, read Configuration. To learn more about the specific configuration options available in this SDK, read LDOptions.

Initializing the client makes a remote request to LaunchDarkly. Depending on your network conditions, it may take a couple hundred milliseconds before the SDK emits the ready event. If you require feature flag values before rendering the page, we recommend bootstrapping the client. If you bootstrap the client, it will emit the ready event immediately. To learn more, read Bootstrapping. To learn about best practices when using other default flag value methods, read Eliminating flicker when using default flag values.

Determine when the client is ready

To find out when the client is ready, you can use one of two mechanisms:

• events
• promises

client.on('ready', () => {
  // initialization succeeded, flag values are now available
  const flagValue = client.variation('flag-key-123abc', false);
  // etc.
});
COPY

try {
  await client.waitForInitialization(5);
  // initialization succeeded, flag values are now available
} catch (err) {
  // initialization failed or did not complete before timeout
}
COPY

Subscribe to flag changes

The SDK does not subscribe to streaming real-time updates automatically when you initialize it.

In some cases, streaming may not be necessary. For example, if you reload your entire application on each update, you will get all the flag values again when the client is re-initialized. If this is your use case, you should leave the streaming value undefined, which is the default.

In other cases, streaming may be required. Subscribing to streaming is the only way to receive real-time updates. If you determine that streaming is necessary for your application, there are two ways to subscribe to streaming:

• Explicitly subscribe to streaming: If you set the streaming configuration option to true, the client will always attempt to maintain a streaming connection.
• Register a change listener: If you subscribe to change or change:flag-key events, the client will open a streaming connection. It will close this streaming connection when you unsubscribe from the event, for example by calling .off('change:flag-key'). Because opening and closing streaming connections can be expensive, you should explicitly enable streaming if your application frequently starts and stops listening to changes.

If you do enable streaming through either of these methods, you will also need EventSource. If you also enable the SDK's useReport configuration option, you will need LaunchDarkly's EventSource polyfill. To learn more, read EventSource.

To learn more, read streaming.

Shut down the client

Shut down the client when your application terminates. To learn more, read Shutting down.

Supported features

This SDK supports the following features:

• Anonymous contexts and users
• Bootstrapping
• Configuration, including
  • Application metadata configuration
  • Service endpoint configuration
• Context configuration
• Evaluating flags
• Flag evaluation reasons
• Flushing events
• Getting all flags
• Identifying and changing contexts
• Inspectors
• Logging
• Private attributes
• Relay Proxy configuration, using proxy mode
• Secure mode
• Sending custom events
• Service endpoint configuration
• Shutting down
• Subscribing to flag changes