Bootstrapping
Read time: 8 minutes
Last edited: Nov 07, 2024
Overview
This topic explains how the bootstrapping feature works in the LaunchDarkly SDKs that support it.
A context is a generalized way of referring to the people, services, machines, or other resources that encounter feature flags in your product. Contexts replace another data object in LaunchDarkly: "users."
Creating contexts and evaluating flags based on them is supported in the latest major versions of most of our SDKs. For these SDKs, the code samples on this page include the two most recent versions.
About 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 end 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 Web 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 Web SDK, 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 customer visits your site, local storage is empty. This means the customer 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 customers have privacy settings that block sites from using their browser's local storage.
- Flag changes that happen while the customer is on the page automatically update the local storage cache, keeping it in sync with the server. However, if the customer 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 customer 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 Bootstrap 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 customer 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 customer'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 or context. 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 edge SDKs to access flag values without processing delays. To learn more, read Edge SDKs. For an example, 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:
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:
JavaScript
Expand JavaScript code sample
To bootstrap flags in the JavaScript SDK, 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.
Here is an example, which assumes you pass the flags on page load:
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:
Alternatively, you can bootstrap feature flags from local storage:
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 end 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 (client-side) SDK with values provided by LaunchDarkly-enabled code on the backend. You can populate the initial set of bootstrap values with a JSON object containing flag metadata derived from calling the server-side SDK's all flags method.
You can use it to set the feature flags to any values you want:
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":
React Web
Expand React code sample
You can bootstrap flags into the React Web SDK the same way you bootstrap flags into the JavaScript SDK: by setting bootstrap in the options included when you initialize the LDClient. To learn how, read JavaScript, above.