Bootstrapping

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.

You typically obtain the bootstrap flag values from a server SDK. The server sends to the browser an HTML page containing the JavaScript and the feature flags your site needs during the initial page render. Your site then bootstraps the LaunchDarkly client using the provided flags during client initialization in the start() function. Feature flags are ready immediately, and clients always receive the latest feature flag values.

Bootstrapping using server-rendered content requires additional setup, but it provides several benefits over using only cached flag values in local storage:

• It provides flag values the very first time a customer visits a page.
• The values are up-to-date even if there is a lag between page visits.
• Bootstrapping from a server does not rely on a customer’s privacy settings to function.

Some SDKs support providing bootstrap values in the identify() function in addition to start(). Providing values in identify() lets you use bootstrap values after an anonymous context logs in as an identified user.

Bootstrapping using server-rendered content

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, usually via the start() function. To learn more, read Getting all flags.

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

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.

Compatibility with local storage caching

Some newer client SDKs support bootstrapping flag values in addition to caching flag evaluations for unique contexts. When flag evaluations are cached to local storage, on subsequent launches the SDK reads the cached values before any network connection is established. The client still initializes and connects to LaunchDarkly’s service to fetch the most recent flag values, but it is not dependent on those values to reach its ready state.

The following SDKs enable local storage caching by default, and you can configure both bootstrapping and local caching independently:

• JavaScript SDK v4.x
• React Web SDK

Other SDKs use the same implementation for both bootstrapping and local storage caching. For these SDKs you cannot configure both bootstrapped flag values and local storage caching. The following SDKs use a single bootstrap configuration parameter to either provide bootstrap flag values or enable local storage caching, but not both:

• JavaScript SDK v3.x
• Electron
• Node.js (client-side)

Using local storage caching instead of bootstrap server values can be useful if you can’t dynamically add bootstrapping data to your page. However, using only local storage caching has these downsides:

• The first time the customer visits your site, local storage is empty. This means the customer receives the site’s default behavior, as specified in the fallback values you provide, before the values from feature flags load. Only after the customer’s second visit does the page use the values in local storage. It’s important to choose effective fallback values to limit rendering delays.
• 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.

For an example of using local storage without bootstrapping on a static site, read Configure local storage for cached contexts.

To learn more, read Caching contexts to local storage.

Client-side SDKs

The bootstrapping feature is available in the following client-side SDKs:

• Electron
• JavaScript
• Node.js (client-side)
• React Server Wrapper
• React Web

Electron

1
const client = LaunchDarkly.initialize(
2
  'example-client-side-id',
3
  user,
4
  {
5
    bootstrap: {
6
      flagKey1: flagValue1,
7
      flagKey2: flagValue2
8
    }
9
  }
10
);

JavaScript

1
import { createClient } from '@launchdarkly/js-client-sdk';
2
3
const context = { kind: 'user', key: 'example-user-key'};
4
5
const client = createClient(
6
  'example-client-side-id', 
7
  context
8
);
9
10
// bootstrapData is the result of your server-side SDK call to get all flags
11
const flags = JSON.parse(bootstrapData)
12
const options = { bootstrap: flags }
13
14
client.start(options);

1
import { createClient } from '@launchdarkly/js-client-sdk';
2
3
const context = { kind: 'user', key: 'example-user-key'};
4
5
const client = createClient(
6
  'example-client-side-id', 
7
  context
8
);
9
10
client.start({
11
  // Load values from a Ruby template directive
12
  bootstrap: <%= client.all_flags_state(user, {client_side_only: true}).to_json %>
13
});

Node.js (client-side)

1
// bootstrapData is the result of your server-side SDK call to get all flags
2
const flags = JSON.parse(bootstrapData)
3
4
function onPageLoad(flags) {
5
  ...
6
7
  const client = LDClient.initialize(
8
    'example-client-side-id',
9
    context,
10
    options = {
11
      bootstrap: flags
12
    }
13
  );
14
15
  ...
16
}

React Server Wrapper

1
// app/page.tsx (Server Component)
2
import { init } from '@launchdarkly/node-server-sdk';
3
import { createLDServerSession, LDIsomorphicProvider } from '@launchdarkly/react-sdk/server';
4
5
const ldBaseClient = init(process.env.LAUNCHDARKLY_SDK_KEY!);
6
7
export default async function Page() {
8
  await ldBaseClient.waitForInitialization({ timeout: 10 });
9
10
  const session = createLDServerSession(ldBaseClient, {
11
    kind: 'user',
12
    key: 'user-key',
13
    name: 'Sandy',
14
  });
15
16
  return (
17
    <LDIsomorphicProvider
18
      session={session}
19
      clientSideId={process.env.LAUNCHDARKLY_CLIENT_SIDE_ID!}
20
    >
21
      <App />
22
    </LDIsomorphicProvider>
23
  );
24
}

For a complete working application, read the isomorphic provider example.

React Web

1
import { createLDReactProvider } from '@launchdarkly/react-sdk';
2
3
// bootstrapData is the result of your server-side SDK call to get all flags
4
const flags = JSON.parse(bootstrapData);
5
6
const LDProvider = createLDReactProvider(
7
  'example-client-side-id',
8
  { kind: 'user', key: 'example-user-key' },
9
  {
10
    bootstrap: flags,
11
  },
12
);

1
import { createLDReactProvider } from '@launchdarkly/react-sdk';
2
3
const LDProvider = createLDReactProvider(
4
  'example-client-side-id',
5
  { kind: 'user', key: 'example-user-key' },
6
  {
7
    startOptions: {
8
      bootstrap: flags,
9
    },
10
  },
11
);