JavaScript Feature Flags

JavaScript Feature Flag Resources/Solutions

  • LaunchDarkly JavaScript Feature Flag SDK – LaunchDarkly
    • An installable feature flag software development kit for JavaScript and single page apps (Ember/Angular/React).  This SDK harnesses the LaunchDarkly app and allows you to target users and manage rollouts.  Feature flags are evaluated in microseconds.
    • Main Website
    • Front-end Flags
    • GitHub Repo
  • JavaScript Feature Flags – Jay Fienberg
    • “This Javascript function gets Feature Flags set in the URL (as fragment and/or query string), set in a browser cookie, and/or via matching a domain name (e.g., localhost, or your test domain name).”
    • Demo
    • GitHub Repo
  • Angular Feature Flags – Michael Taranto
    • “An AngularJS module that allows you to control when you release new features in your app by putting them behind feature flags/switches. This module only supports Angular v1.2 and up. The basic premise is you write your feature and wrap it up in a directive, then where you implement that directive in your markup you add the feature-flag directive to the same element. You can then pass the key of the flag to this directive to resolve whether of not this feature should be enabled.”
    • GitHub Repo
  • Ember Feature Flags – Kate Gengler
    • “An ember-cli addon to provide feature flags. This addon injects a property features onto your routes, controllers and components.”
    • GitHub Repo
  • Ember Feature Flag Guide – Ember
    • “When a new feature is flagged it is only available in canary builds (if enabled at runtime). When it is time for the next beta cycle to be started (generally 6-12 week cycles) each feature will be evaluated and those features that are ready will be enabled in the next beta (and subsequently automatically enabled in all future canary builds). If a given feature is deemed unstable it will be disabled in the next beta point release, and not be included in the next stable release. It may still be included in the next beta cycle if the issues/concerns have been resolved. Once the beta cycle has completed the final release will include any features that were enabled during that cycle. At this point the feature flags will be removed from the canary and future beta branches, and the feature flag will no longer be used.”
    • GitHub Repo
  • Flux Feature Flags – Dave King
    • “An example of using the Flux application architecture to make amazing feature flags.”
    • GitHub Repo
  • Feature Toggles – Eric Elliot
    • “A painless feature toggle system in JavaScript. Decouple development and deployment.”
    • GitHub Repo
  • NPM Feature Toggles – Alex Lawrence
    • “A painless feature toggle system in JavaScript. Decouple development and deployment.”
    • GitHub Repo

———————

LaunchDarkly JavaScript SDK Reference

This reference guide documents all of the methods available in the LaunchDarkly client-side JavaScript SDK, and explains in detail how these methods work.

For client-side JavaScript only

The JavaScript SDK is intended for client-side (browser) feature flags only.

If you’ve got 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.

Getting started


There are two ways to install our JavaScript SDK– as an npm module, or as a JavaScript snippet served from LaunchDarkly’s CDN.

If you haven’t taken a look at our Quickstart guide yet, we recommend starting there to see how install our SDK into your client-side JavaScript as an npm module. In most cases, it should be as simple as running the following in your project:

npm install --save ldclient-js

To load our JavaScript SDK as a script tag, include 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:

<script crossorigin="anonymous" src="https://app.launchdarkly.com/snippet/ldclient.min.js"></script>

Browser support


The LaunchDarkly client-side JavaScript SDK supports the following browsers:

  • Chrome (any recent)
  • Firefox (any recent)
  • Safari (any recent)*
  • Internet Explorer (IE10+)*
  • Edge (any recent)*
  • Opera (any recent)*
  • These browsers do not support streaming new flags to connected clients, even when client.on(‘change’) is called.

If you need streaming support, and you wish to support browsers that do not support EventSource natively, you can install a polyfill, such as eventsource.

You can load the polyfill via a script tag in the <head> before the script where you initialize LDClient:

<script src="/public/eventsource-polyfill.js"></script>

If you use webpack or browserify, make sure to require the polyfill before LDClient is initialized.

Initializing the client


To create a client instance, you need an environment ID (available on your account settings page). Environment IDs are not secret– they can be safely exposed in your client-side code.

In practice, you will probably want to templatize your environment 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 all 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.

Here’s a basic example showing how to initialize the client:

var user = {
  "key": "aa0ceb"
};
var ldclient = LDClient.initialize('YOUR_ENVIRONMENT_ID', user);

The client will emit a ready event when it has been initialized. Once it has been initialized, you can safely callvariation to access your feature flags:

ldclient.on('ready', function() {
  console.log("It's now safe to request feature flags");
  var showFeature = client.variation("YOUR_FEATURE_KEY", false);

  if (showFeature) {
    ...
  } else {
    ...
  }
});

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 (see the Bootstrapping section). If the client is bootstrapped, it will emit the ready event immediately.

Making feature flags available to the client-side SDK

Feature flags must marked available to the client-side SDK (see your feature flag’s settings page) before they can be used in variation calls on the front-end. If you request a feature flag that is not available, you’ll receive the default value for that flag.

Users


Let’s walk through the user JSON in more detail. The most important attribute is the user key– in this case we’ve used the hash "aa0ceb". The user key is the only mandatory user attribute. The key should also uniquely identify each user. You can use a primary key, an e-mail address, or a hash, as long as the same user always has the same key. We recommend using a hash if possible.

Here’s a more complete example of a user:

var user = {
  "key": "aa0ceb",
  "firstName": "Ernestina",
  "lastName": "Evans",
  "email": "ernestina@example.com",
  "custom": {
    "groups": ["Google", "Microsoft"]
  }
};

All of the other attributes (like firstName, email, and the custom attributes) are optional. The attributes you specify will automatically appear on our dashboard, meaning that you can start segmenting and targeting users with these attributes.

Besides the key, LaunchDarkly supports the following attributes at the “top level”. Remember, all of these are optional:

  • ip: Must be an IP address. If you provide an IP, LaunchDarkly will use a geolocation service to automatically infer a country for the user (unless you’ve already specified one).
  • firstName: Must be a string. If you provide a first name, you can search for users on the Users page by name.
  • lastName: Must be a string. If you provide a last name, you can search for users on the Users page by name.
  • country: Must be a string representing the country associated with the user.
  • email: Must be a string representing the user’s e-mail address. If an avatar URL is not provided, we’ll useGravatar to try to display an avatar for the user on the Users page.
  • avatar: Must be an absolute URL to an avatar image for the user.
  • name: Must be a string. You can search for users on the User page by name
  • anonymous: Must be a boolean. See the section below on anonymous users for more details.

In addition to built-in attributes, you can pass us any of your own user data by passing custom attributes, like thegroups attribute in the example above.

A note on types

Most of our built-in attributes (like names and e-mail addresses) expect string values. Custom attribute values can be strings, booleans (like true or false), numbers, or lists of strings, booleans or numbers.

If you enter a custom value on our dashboard that looks like a number or a boolean, it’ll be interpreted that way.

Custom attributes are one of the most powerful features of LaunchDarkly. They let you target users according to any data that you want to send to us– organizations, groups, account plans– anything you pass to us becomes available instantly on our dashboard.

Anonymous users


You can also distinguish logged-in users from anonymous users in the SDK, as follows:

var user = {"key":"aa0ceb", "anonymous": true};

You will still need to generate a unique key for anonymous users– session IDs or UUIDs work best for this.

Anonymous users work just like regular users, except that they won’t appear on your Users page in LaunchDarkly. You also can’t search for anonymous users on your Features page, and you can’t search or autocomplete by anonymous user keys. This is actually a good thing– it keeps anonymous users from polluting your Users page!

Variation


The variation method determines which variation of a feature flag a user receives.

ldclient.variation("your.feature.key", false);

variation calls take the feature flag key, an LDUser, and a default value.

The default value will only be returned if an error is encountered– for example, if the feature flag key doesn’t exist or the user doesn’t have a key specified.

The variation call will automatically create a user in LaunchDarkly if a user with that user key doesn’t exist already. There’s no need to create users ahead of time (but if you do need to, take a look at Identify).

Track


The track method allows you to record actions your users take on your site. This lets you record events that take place client-side. In LaunchDarkly, you can tie these events to goals in A/B tests. Here’s a simple example:

ldclient.track("Signed up");

Subscribing to feature flag changes


The client uses an event emitter pattern to allow you to subscribe to feature flag changes in real time. To subscribe to all feature flag changes, listen for the change event:

client.on('change', function(settings) {
  console.log('flags changed:', settings);
});

The settings object will contain a map of updated feature flag keys and values. The map will only contain the keys to flags that have changed. You can also subscribe to specific flags:

client.on('change:YOUR_FLAG_KEY', function(value, previous) {
  console.log('YOUR_FLAG_KEY changed:', value, '(' + previous + ')');
});

Bootstrapping


Bootstrapping refers to providing the LaunchDarkly client object with an initial, immediately available set of feature flag values so that on page load variation can be called with no delay.

The preferred approach to bootstrapping is to populate the bootstrap values (a map of feature flag keys to flag values) from your backend. LaunchDarkly’s server-side SDKs have a function called all_flags– this function provides the initial set of bootstrap values. You can then provide these values to your front-end as a template. Depending on your templating language, this might look something like this:

var client = LDClient.initialize('YOUR_ENVIRONMENT_ID', user, options = {
  bootstrap: {
    {{ ldclient.all_flags(user) }} // this is a template directive
  }
});

If you bootstrap from the server-side, feature flags will be ready immediately, and clients will always receive the latest feature flag values.

Alternatively, you can bootstrap feature flags from local storage:

var client = LDClient.initialize('YOUR_ENVIRONMENT_ID', user, options = {
  bootstrap: 'localStorage'
});

When using local storage, the client will store the latest flag settings in local storage. On page load, the previous settings will be used and the ‘ready’ event will be emitted immediately. This means that on page load, the user may see cached flag values until the next page load.

You can still subscribe to flag changes if you’re using local storage.

Secure mode


Secure mode ensures that feature flag settings for a user are kept private, and that one user cannot inspect the settings for another user. Secure mode works by having you include a server-generated HMAC SHA256 hash of your user key, signed with the SDK key for your environment.

You can enable secure mode for each environment on your account settings page:

You should send the computed hash for your user in the options array during client initialization:

var client = LDClient.initialize('YOUR_ENVIRONMENT_ID', user, options = {
  hash: "SERVER_GENERATED_HASH"
});

Each of our server-side SDKs includes a method to compute the secure mode hash for a user. You can pass this to your front-end code in a template. For example:

var client = LDClient.initialize('YOUR_ENVIRONMENT_ID', user, options = {
  hash: {{ ldclient.secure_mode_hash(user) }} // this is a template directive, and the ldclient instance here is your server-side SDK client
});

To compute the hash yourself, locate the SDK key for your environment on your account settings page. Then, compute an HMAC SHA256 hash of your user key, using your SDK key as a secret. Here’s what this would look like in Node.js:

var crypto = require('crypto');
var hmac = crypto.createHmac('sha256', 'YOUR_SDK_KEY');
hmac.update('YOUR_USER_KEY');
hash = hmac.digest('hex');

Changing the user context


You may wish to change the user context dynamically and receive the new set of feature flags for that user or generate events for the new user. For example, on a sign-in page in a single-page app, you might initialize the client with an anonymous user. When the user logs in, you’d want the feature flag settings for the authenticated user. To do this, you can call the identify function:

client.identify(newUser, hash, function() {
  console.log("New user's flags available");
});

The hash parameter is the hash for the new user, assuming that the user’s key has changed. It is only required in secure mode– if secure mode is not enabled, you can pass in null for the hash.

Tracking click and pageview events


If you’ve defined click or pageview goals (see Running A/B tests) in LaunchDarkly, they’ll be sent automatically once the client has been initialized. You do not have to do anything else with the client to send click or pageview goals.

Single-page apps

The SDK automatically handles URL changes (made via the HTML5 history API or by changing the URL hash fragment), and will trigger pageview and click events correctly.