• Home
  • Integrations
  • SDKs
  • Guides
  • API docs
No results for ""
EXPAND ALL

EDIT ON GITHUB

Bootstrapping

Read time: 5 minutes
Last edited: Aug 12, 2022

Overview

This topic explains how the bootstrapping feature works in the LaunchDarkly SDKs that support it.

Understanding the bootstrapping feature

The bootstrapping feature lets you decrease startup times for client-side SDKs by providing them with an initial set of flag values that are immediately available during client initialization. The SDK serves these values to the user before it has established a connection to LaunchDarkly so there is no inconsistency in the flag variations they receive.

There are two methods of bootstrapping the client:

  • Bootstrapping using local storage
  • Bootstrapping using server-rendered content

Each method has its advantages and drawbacks, explained below.

Bootstrapping using local storage

The following applies to bootstrapping with SDKs that run in a browser, including the JavaScript SDK and the React SDK. To learn how to bootstrap using other client-side SDKs, read Electron and Node.js (client-side).

If you are using the JavaScript or React SDKs, the client stores the latest flag settings in the browser's local storage so the client can initialize itself without an additional delay from fetching the flags from the LaunchDarkly servers. The client still initializes and connects to LaunchDarkly's service to fetch the most recent flag values, but is no longer dependent on those values to reach its ready state.

The local storage cache updates when new values arrive. On subsequent page loads, the client fetches the most recently cached flag values from local storage and emits the ready event immediately.

Bootstrapping using local storage has some benefits:

  • It is easy to set up, and requires little maintenance.
  • It is useful when you can't dynamically add bootstrapping data to the page.

Bootstrapping using local storage also has some downsides:

  • The first time the user visits your site, local storage is empty. This means the user will receive the site's default behavior before the values from feature flags load, and only after their second visit will the page utilize the values in local storage.
  • If there is a long time between page visits, the values stored in local storage may be out of date.
  • Some users have privacy settings that block sites from using their browser's local storage.
  • Flag changes that happen while the user is on the page automatically update the local storage cache, keeping it in sync with the server. However, if the user is not on the page when the flag change happens, the flag value in local storage may go out of sync with the server. The next time this user visits that page, they could experience a flicker because of the client using the previous flag value from local storage. If you bootstrap using local storage, it's important to choose effective defaults for your flag values to limit rendering delays.

For an example of bootstrapping from local storage on a static site, read Bootstrapping using local storage.

Bootstrapping using server-rendered content

In this method, the server sends to the browser an HTML page containing the JavaScript and the feature flags your site needs during the initial render. Your site then bootstraps the LaunchDarkly client with those flags. Feature flags are ready immediately, and clients always receive the latest feature flag values.

Bootstrapping using server-rendered content requires more setup than bootstrapping from local storage, but provides more benefits.

The benefits of bootstrapping using server-rendered content include:

  • It provides values the first time a user visits a page.
  • Bootstrapped values will not become out of date if there is a lag between page visits.
  • It does not rely on a user's privacy settings to function.

The downside to bootstrapping using server-rendered content is that it requires significantly more set up work than bootstrapping from local storage.

For a demonstration of bootstrapping from the server, visit our hello-bootstrap GitHub repository.

All of the server-side SDKs have a function, named some variation of allFlagsState, to evaluate flags on behalf of a specified user. We recommend populating the initial set of bootstrap values with a JSON object containing flag metadata derived from calling the server-side SDK's all flags method.

If your back end passes values to your front end on page load, you can call your server-side SDK's all flags function on page load and pass the results as a parameter to your front-end initialization code. To learn more, read Getting all flags.

You can also use LaunchDarkly's Cloudflare Workers integration to access flag values without processing delays. To learn more, read Using LaunchDarkly with Cloudflare Workers.

Client-side SDKs

This feature is available in the following client-side SDKs:

Electron

Expand Electron code sample

You can use bootstrapping on the Electron SDK with values provided by LaunchDarkly-enabled code on the backend.

You can use it to set the feature flags to any values you want:

const client = LaunchDarkly.initialize(
'YOUR_CLIENT_SIDE_ID',
user,
{
bootstrap: {
flagKey1: flagValue1,
flagKey2: flagValue2
}
}
);

If you set bootstrap to the string "localStorage", the client tries to get flag values from persistent storage, using a unique key that is based on the user properties.

In Electron, persistent storage consists of files in the userData directory. If the client finds flag values stored for this user, it uses them and starts up immediately in a ready state, but also makes a background request to LaunchDarkly to get the latest values and stores them as soon as it receives them.

Here's how to use this mode:

const client = LaunchDarkly.initializeInMain(
'YOUR_CLIENT_SIDE_ID',
user,
{
bootstrap: 'localStorage'
}
);

JavaScript

Expand JavaScript code sample

Here is an example of how to bootstrap flags into the JavaScript client, if it passes the flags on page load:

function onPageLoad(flags) {
...
const client = LDClient.initialize(
'YOUR_CLIENT_SIDE_ID',
user,
options = {
bootstrap: flags
}
);
...
}

If you can invoke your backend dynamically, such as in Ruby with a template directory, you can inline the function invocation and request that the SDK return only the client-side flags.

Here is an example of how to bootstrap flags into the JavaScript client, if you acquire the flags from a Ruby template directive:

const ldclient = LDClient.initialize(
'YOUR_CLIENT_SIDE_ID',
user,
options = {
// Load values from a Ruby template directive
bootstrap: {{
client.all_flags_state(user, {client_side_only: true})
}}
}
);

Alternatively, you can bootstrap feature flags from local storage:

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

When the client uses local storage, it stores the latest flag settings there. On page load, it uses the previous settings and emits the 'ready' event immediately. This means that on page load, the user may receive cached flag values until the next page load.

You can still subscribe to flag changes if you use local storage.

Node.js (client-side)

Expand Node.js (client-side) code sample

You can use bootstrapping on the Node.js SDK with values provided by LaunchDarkly-enabled code on the backend.

You can use it to set the feature flags to any values you want:

const client = LaunchDarkly.initialize(
'YOUR_CLIENT_SIDE_ID',
user,
{
bootstrap: {
flagKey1: flagValue1,
flagKey2: flagValue2
}
}
);

A more useful mode in a client-side Node application is to bootstrap from locally cached values. In this mode, if no values have been cached yet, the SDK obtains flags from LaunchDarkly and then caches them in persistent storage. The next time you start, the cached flags are immediately available, and the SDK also contacts LaunchDarkly in the background to obtain updated values.

To activate this mode, use the special string "localStorage":

const client = LaunchDarkly.initialize(
'YOUR_CLIENT_SIDE_ID',
user,
{
bootstrap: 'localStorage'
}
);

React

Expand React code sample

You can bootstrap flags into the React SDK the same way you bootstrap flags into the JavaScript client.

You can also use the optional flags property to bootstrap the React SDK. If you specify flags, the React SDK only subscribes for updates to those flags, and sets the fallback values for those flags. If you do not specify this property, the React SDK subscribes to all flags. This property is optional.

Specify the flags property as a JSON object containing flag metadata derived from calling the server-side SDK's all flags method. The flag keys must be in their original form, as known to LaunchDarkly, rather than in their camel-cased form. Each flag's value is passed along to the resulting JavaScript SDK variation invocation and used as the flag's default value in the case of an error.

Here is an example:

{
"flags": {
"my-bool-flag": true,
"my-int-flag": 5
}
}

To learn more, read the React Web SDK reference.