Bootstrapping

Overview

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

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
• JavaScript
• Node.js (client-side)
• React Web

Electron

const client = LaunchDarkly.initialize(
  'client-side-id-123abc',
  user,
  {
    bootstrap: {
      flagKey1: flagValue1,
      flagKey2: flagValue2
    }
  }
);
COPY

const client = LaunchDarkly.initializeInMain(
  'client-side-id-123abc',
  user,
  {
    bootstrap: 'localStorage'
  }
);
COPY

JavaScript

// bootstrapData is the result of your server-side SDK call to get all flags
const flags = JSON.parse(bootstrapData)
function onPageLoad(flags) {
  ...
  const client = LDClient.initialize(
    'client-side-id-123abc',
    context,
    options = {
      bootstrap: flags
    }
  );
  ...
}
COPY

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

const client = LDClient.initialize('client-side-id-123abc', user, options = {
  bootstrap: 'localStorage'
});
COPY

Node.js (client-side)

// bootstrapData is the result of your server-side SDK call to get all flags
const flags = JSON.parse(bootstrapData)
function onPageLoad(flags) {
  ...
  const client = LDClient.initialize(
    'client-side-id-123abc',
    context,
    options = {
      bootstrap: flags
    }
  );
  ...
}
COPY

const client = LDClient.initialize(
  'client-side-id-123abc',
  context,
  {
    bootstrap: 'localStorage'
  }
);
COPY

React Web