Bootstrapping

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:

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

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:

1
const client = LaunchDarkly.initializeInMain(
2
  'example-client-side-id',
3
  user,
4
  {
5
    bootstrap: 'localStorage'
6
  }
7
);

The JavaScript client SDK v4.x stores flag values for unique contexts in local storage by default, with no configuration required. You can optionally set the maximum number of unique contexts cached locally by setting maxCachedContexts at startup.

Set maxCachedContexts to 0 to disable bootstrapping from local storage and clear any cached contexts. Setting disableCache to true disables bootstrapping from local storage, but leaves any existing local storage in place.

To learn more, read Interface LDOptions.

JavaScript SDK v3.7+ requires you to enable caching contexts to local storage at initialization using the bootstrap option:

1
import { createClient } from '@launchdarkly/js-client-sdk';
2
3
const context = { kind: 'user', key: 'example-user-key'};
4
5
// Local storage is enabled by default
6
// You can optionally configure the maximum number of cached contexts (default is 5)
7
const options = { maxCachedContexts: 3 };
8
9
const client = createClient(
10
  'example-client-side-id',
11
  context,
12
  options
13
);
14
15
client.start();

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

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

To bootstrap flags from server-rendered content using the JavaScript SDK, 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.

In JavaScript SDK v4.x you can provide server flag values in the bootstrap option to start() or identify(). This lets you use server-provided values immediately without waiting for client-side initialization. It also lets you to use bootstrap values after an anonymous context logs in as an identified user.

In JavaScript SDK v3.7+ you can provide the bootstrap option only once, during initialization. This lets you bootstrap initial flag values for an anonymous context, but does not allow for bootstrapping after the context logs in as an identified user. Using bootstrap with server-rendered content also disables caching context to local storage with SDK v3.7+.

Here is an example, which assumes you pass the flags on page load:

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);

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:

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
});

You can also read about How to bootstrap when serving from a CDN, not a backend.

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:

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
}

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":

1
const client = LDClient.initialize(
2
  'example-client-side-id',
3
  context,
4
  {
5
    bootstrap: 'localStorage'
6
  }
7
);

Starting from version 4.x of the React Web SDK, you can use our React Server Component support to facilitate a special kind of bootstrapping through our LDIsomorphicProvider.

If you want to take full advantage of React Server Components for faster load time and continue getting live updates in the client, here’s how:

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
}

LDIsomorphicProvider is an async React Server Component that evaluates all flags on the server and bootstraps the client-side SDK with those values. This allows the client-side SDK to start immediately with real values instead of defaults.

After hydration, the client SDK opens a streaming connection and live flag updates propagate normally to all hooks.

Server Components inside the provider tree can call session.boolVariation(...) directly. Client Components use the standard hooks, such as useBoolVariation. They read from the bootstrapped data on first render and receive live updates afterwards.

Here is a list of available properties for LDIsomorphicProvider:

In the React Web SDK v4.0 and later, bootstrap is a top-level option on createLDReactProvider. It accepts a plain key-value object, such as { 'example-flag-key': true }, or the output of the server-side SDK’s allFlagsState().toJSON(), which includes $flagsState and $valid metadata.

To bootstrap flags in the React Web 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 that assumes you pass the flags on page load:

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
);

You can also pass bootstrap data through startOptions.bootstrap. The top-level bootstrap option is merged into startOptions.bootstrap when the client starts. If you provide both, the top-level value takes precedence.

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
);

If you are migrating from the React Web SDK v3.x, the bootstrap option used to be nested inside options. To learn more, read the React Web SDK 3.x to 4.0 migration guide.