Requirements and polyfills

Read time: 4 minutes

Last edited: Sep 30, 2024

Overview

This topic explains how to add different types of polyfills in the JavaScript SDK.

Web browsers vary widely in their support of specific features and standards. It is common in JavaScript development to use polyfills to ensure the widest possible compatibility. Polyfills are scripts that implement a feature in case it is not built into the browser.

Three features that the LaunchDarkly JavaScript SDK uses that may not be available on every browser are Promise, EventSource, and document.querySelectorAll().

If you use REPORT, you need the LaunchDarkly EventSource polyfill

If you enable the JavaScript SDK's useReport configuration option and want to use streaming, you must use the LaunchDarkly EventSource polyfill. This is true whether or not your browser already supports EventSource. To learn more, read EventSource.

Add a polyfill

For each of these features, there are two ways you can provide the polyfill script.

The first way is to load the polyfill script directly from a CDN that hosts the package, with a <script> tag within the <head> element of your page. You must put the <script> tag for the polyfill before any scripts that make use of the LaunchDarkly SDK.

Here is how to load a polyfill script directly from a CDN:

<script src="[URL of the polyfill script]"></script>

If you are using a package manager such as NPM or Yarn, and using require() to load modules at runtime, you would first add the polyfill package to your project:

npm install package-name-of-polyfill@package.version.number

Then, make sure that you require the polyfill module prior to initializing the LaunchDarkly client:

require('package-name-of-polyfill');

You only need to use one of these methods. You do not need to use both a CDN and a package manager.

Install polyfills for specific features

Three features that the LaunchDarkly SDK uses that may not be available on every browser are Promise, EventSource, and document.querySelectorAll(). This section describes how to install a polyfill for each of them.

Promise

The JavaScript SDK relies heavily on JavaScript Promises. Browsers that do not support Promise include Internet Explorer and older versions of Microsoft Edge. If you need to support these browsers, you will need to install a polyfill for Promise, such as es6-promise.

To install a polyfill for Promise:

<!-- loading polyfill from CDN -->
<script src="https://unpkg.com/es6-promise@4.2.4/dist/es6-promise.auto.min.js"></script>

EventSource

The JavaScript SDK uses EventSource to provide a live streaming connection to LaunchDarkly, if you have enabled streaming.

By default, the JavaScript SDK client opens a streaming connection if you subscribe to change or change:flag-key events. You can also open a streaming connection explicitly by setting the streaming configuration option or using the setStreaming method. If you never enable streaming, you do not need EventSource. To learn more, read streaming.

EventSource is widely available in browsers, except for Internet Explorer and Microsoft Edge. If you want to support these browsers, and you need streaming support, you can install a polyfill such as event-source-polyfill.

To install a polyfill for EventSource:

<!-- loading polyfill from CDN -->
<script src="https://unpkg.com/event-source-polyfill@0.0.12/src/eventsource.min.js"></script>

If you enable the JavaScript SDK's useReport configuration option and want to use streaming, you must install the LaunchDarkly EventSource polyfill to provide streaming support. This is true whether or not your browser already supports EventSource.

To install LaunchDarkly's EventSource polyfill:

npm install launchdarkly-eventsource

document.querySelectorAll()

The JavaScript SDK uses querySelectorAll to support click events for Experimentation. If you never use click conversion metrics, you do not need querySelectorAll. To learn more, read Clicked or tapped conversion metrics.

querySelectorAll is widely available in browsers, except in old versions of Internet Explorer. If you want to support these, and you need Experimentation support, you can install a polyfill such as polyfill-queryselector.

To install a polyfill for querySelectorAll:

<!-- loading polyfill from CDN -->
<script src="https://unpkg.com/polyfill-queryselector@1.0.2/querySelector.js"></script>