ldclient-js-credentials
Advanced tools
This is the official LaunchDarkly client-side JavaScript SDK. This SDK does two things:
The LaunchDarkly client-side JavaScript SDK supports the following browsers:
* 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
event-source-polyfill.
You can load the polyfill via a script tag in the <head> before the script where you initialize LDClient:
<script src="https://unpkg.com/event-source-polyfill@0.0.12/src/eventsource.min.js"></script>
npm install event-source-polyfill@0.0.12
Then import it before the module that initializes the LaunchDarkly client:
require('event-source-polyfill');
If you need to run A/B tests on IE7 or IE8 you will need to install a polyfill
for document.querySelector() such as
polyfill-queryselector.
You can load the polyfill via a script tag in the <head> before the script where you initialize LDClient:
<script src="https://unpkg.com/polyfill-queryselector@1.0.2/querySelector.js"></script>
npm install polyfill-queryselector@1.0.2
Then import it before the module that initializes the LaunchDarkly client:
require('polyfill-queryselector');
Newer versions of the SDK use Promise. If you need to support older browsers, you will
need to install a polyfill for it, such as es6-promise.
You can load the polyfill via a script tag in the <head> before the script where you initialize LDClient:
<script src="https://unpkg.com/es6-promise@4.2.4/dist/es6-promise.auto.min.js"></script>
npm install es6-promise@4.2.4
Then import it before the module that initializes the LaunchDarkly client:
require('es6-promise/auto');
There are two ways to install the client-side SDK:
Via the npm package: npm install --save ldclient-js
A minimized version of the script is also hosted on our CDN, and can be
included via a script tag:
<script src="https://app.launchdarkly.com/snippet/ldclient.min.js">
To create a client instance, pass your environment's client-side ID (available
on your
account settings page) and
user context to the LDClient.initialize function:
var user = { key: 'user.example.com' };
var client = LDClient.initialize('YOUR_CLIENT_SIDE_ID', user);
The client will emit a ready event when it has been initialized. Once it has
been initialized, call variation to access your feature flags:
client.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 approximately 100 milliseconds before the ready event is emitted. If you require feature flag values before rendering the page, we recommend bootstrapping the client. If the client is bootstrapped, it will emit the ready event immediately.
Note: 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.
You can also fetch all feature flags for a user:
var flags = client.allFlags();
This will return a key / value map of all your feature flags. The map will
contain null values for any flags that would return the fallback value (the
second argument that you normally pass to variation). Note that this will send
analytics events to LaunchDarkly as if you'd called variation for every
feature flag.
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 allFlags-- 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 user = {key: 'user.example.com'};
var client = LDClient.initialize('YOUR_CLIENT_SIDE_ID', user, options = {
bootstrap: {
{{ ldclient.all_flags(user) }}
}
});
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_CLIENT_SIDE_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 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 user = { key: 'user.example.com' };
var client = LDClient.initialize(
'YOUR_CLIENT_SIDE_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_CLIENT_SIDE_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');
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 + ')');
});
If you've defined click or pageview goals 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.
You can send custom events by calling the client's track method. For example:
client.track('Signed up');
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.
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 may 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.
To build the module, first run npm install. Then run npm run build. You can
also run npm run watch to rebuild the module automatically on file change.
To run the tests, run npm run test.
Here are resources from our awesome community:
FAQs
LaunchDarkly SDK for JavaScript
We found that ldclient-js-credentials demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.