JavaScript SDK reference

Read time: 3 minutes

Last edited: Jul 28, 2021

This reference guide documents all of the methods available in the client-side JavaScript SDK, and explains in detail how these methods work. If you want to dig even deeper, our SDKs are open source. To learn more, read JavaScript SDK GitHub repository. The online API docs contain the programmatic definitions of every type and method. Additionally you can clone and run a sample application using this SDK.

For client-side JavaScript only

Our JavaScript SDK is intended for client-side (browser) feature flags only. If you have a Node.js application and are looking to set up LaunchDarkly on the server-side, read Node.js SDK reference.

This SDK does two things:

Makes feature flags available to your client-side (front-end) JavaScript code.
Sends click, pageview, 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. Promise is always required, 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.

Do Not Track and ad blocking software

The JavaScript SDK respects the Do Not Track events header. If an end-user has Do Not Track enabled in their browser, the SDK does not send analytics events for flag evaluations or goals to events.launchdarkly.com. In addition, ad-blocking software may block analytics events from being sent. This does not impact feature flag evaluations.

Getting started

Building on top of our Getting Started guide, the following steps will get you started with using the LaunchDarkly SDK in your JavaScript code.

The first step is to make the LaunchDarkly SDK available as a dependency. There are two ways to make our JavaScript SDK available: as a module with a package manager, or with a script tag.

Package manager

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

1npm install --save launchdarkly-js-client-sdk

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 LaunchDarkly SDK into your code.

Here are two examples in commonly used frameworks:

1// using require()
2const LDClient = require('launchdarkly-js-client-sdk');
3
4// using ES2015 imports
5import * as LDClient from "launchdarkly-js-client-sdk";

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

Script tag

To load our JavaScript SDK as a script tag, include one of the following in the <head> tag of your site on any pages where you need feature flags or want to track A/B testing goals.

Note that script tags with sources from unpkg and jsdelivr are not intended to be used on production environments as these introduce a critical dependency on a third-party service. The unpkg and jsdelivr scripts are intended to be used only for ease of development and getting started. In production environments, it is highly recommended that the LaunchDarkly SDK is self-hosted alongside your other JavaScript resources.

Here is an example of code to include in the <head> tag of your site:

1<!-- The script tag shown here automatically updates to the
2     newest release that has a major version of 2. A minor
3     version can be specified by including it in the url.
4     See https://unpkg.com for additional examples and information.
5
6     This method is not recommended for production use. -->
7<script crossorigin="anonymous" src="https://unpkg.com/launchdarkly-js-client-sdk@2"></script>

Initializing the client

Once the dependency is installed, initialize the LaunchDarkly client. To create a client instance, you need your environment's client-side ID, available on your account settings page. Client-side IDs are not secret and you can expose them in your client-side code without risk.

In practice, you should 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 user viewing the page. You must pass a user context to the SDK during initialization before requesting any feature flags with variation. Failure to pass a valid user context to the SDK during initialization will result in a 400 error.

Here is an example showing how to initialize the client:

1var user = {
2  "key": "aa0ceb"
3};
4var ldclient = LDClient.initialize('YOUR_CLIENT_SIDE_ID', user);

Initialization delay

Out of the box, initializing the client will make a remote request to LaunchDarkly, so it may take 100 milliseconds or more before the ready event is emitted. If you require feature flag values before rendering the page,we recommend bootstrapping the client. To learn more, read Bootstrapping. If the client is bootstrapped, it will emit the ready event immediately.

The client emits a ready event when it has been initialized. Once it has been initialized, you can safely call variation to access your feature flags:

1ldclient.on('ready', function() {
2  console.log("It's now safe to request feature flags");
3  var showFeature = ldclient.variation("YOUR_FEATURE_KEY", false);
4
5  if (showFeature) {
6    ...
7  } else {
8    ...
9  }
10});

Streaming Updates

The SDK does not subscribe to streaming real-time updates automatically when it is initialized. As a side effect, subscribing to the SDK's change event by calling .on('change'). will cause the SDK to open a streaming connection to LaunchDarkly. This is the only way to receive realtime updates.

Making feature flags available to the client-side SDK

Feature flags must be marked available to the client-side SDK before they can be used in variation calls on the front-end. Configure this option on your feature flag's Settings page.

If you request a feature flag that is not available, you'll receive the default value for that flag. If you always want flags marked as available to the client-side SDK by default, you can check the "Make new flags available to the client-side (JavaScript) SDK by default" in your project settings.

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

Supported features

This SDK supports the following features: