JavaScript SDK reference

Read time: 4 minutes

Last edited: Dec 04, 2021

Overview

This reference guide documents all of the methods available in the client-side JavaScript SDK, and explains in detail how these methods work. LaunchDarkly's 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. You can also try this SDK out by cloning and running a sample application.

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. In addition, ad-blocking software may block analytics events from being sent. This does not impact feature flag evaluations.

Getting started

After you complete the Getting Started process, follow these instructions to start 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.

Do not use script tags from unpkg or jsDelivr in production

The script tag in the self-hosted example below references a script which is deployed alongside other JavaScript resources in your application. We recommend that you use this method in production.

Do not use script tags with sources from unpkg and jsDelivr in production environments. 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, we strongly recommend 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<script src="path/to/ldclient.min.js"></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 in the Projects tab of your account settings page. Be sure to use a client-side ID. Client-side IDs are not secret and you can expose them in your client-side code without risk. Never embed a server-side SDK key into a client-side application.

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 client = 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:

1client.on('ready', function() {
2  console.log("It's now safe to request feature flags");
3  var showFeature = client.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 this SDK

You must make feature flags available to client-side SDKs before the flags can be evaluated. If an SDK tries to evaluate a feature flag that is not available, the user will receive the default value for that flag.

To make a flag available to this SDK, check the SDKs using Client-side ID checkbox during flag creation, or on the flag's Settings tab. To make all of a project's flags available to this SDK by default, check the SDKs using Client-side ID checkbox 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: