JavaScript SDK reference
Read time: 3 minutes
Last edited: Jun 18, 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.
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, head to our 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, 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.
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 should be as simple as running one of the following in your project:
1npm install --save launchdarkly-js-client-sdk
If you are using a package manager, and then 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');34// using ES2015 imports5import * 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.
1<!-- The script tag shown here automatically updates to the2 newest release that has a major version of 2. A minor3 version can be specified by including it in the url.4 See https://unpkg.com for additional examples and information.56 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's a basic example showing how to initialize the client:
1var user = {2 "key": "aa0ceb"3};4var ldclient = LDClient.initialize('YOUR_CLIENT_SIDE_ID', user);
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 will emit 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);45 if (showFeature) {6 ...7 } else {8 ...9 }10});
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.
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.
Supported features
This SDK supports the following features: