chore: adding better bootstrap support for react sdk (#1194)

This PR will allow developers to directly set bootstrap data on the sdk
provider.

I think this is helpful in order to reasonably preserve the non-deferred
start case.

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/launchdarkly/js-core/pull/1194"
target="_blank">
  <picture>
<source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-open-in-devin-review-dark.svg?v=1">
<img
src="https://static.devin.ai/assets/gh-open-in-devin-review-light.svg?v=1"
alt="Open with Devin">
  </picture>
</a>
<!-- devin-review-badge-end -->


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Touches provider initialization behavior by altering the
`client.start()` options, which could affect startup/flag hydration if
callers relied on previous `startOptions` semantics.
> 
> **Overview**
> Adds a first-class `bootstrap` option to `createLDReactProvider`, and
when auto-starting it now merges that value into the `client.start()`
options (overriding any `startOptions.bootstrap`).
> 
> Updates unit coverage to assert the new merge/precedence behavior, and
extends the migration docs to explain how to pass bootstrap data in the
new SDK.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
da8201d. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: joker23

packages/sdk/react/__tests__/client/provider/LDReactProvider.test.tsx

@@ -20,7 +20,6 @@ jest.mock('../../../src/client/LDReactClient', () => ({
 }));
 
 // ─── createLDReactProviderWithClient ────────────────────────────────────────
-
 it('renders children', () => {
   const client = makeMockClient();
   const Provider = createLDReactProviderWithClient(client);
@@ -219,6 +218,31 @@ describe('createLDReactProvider (convenience factory)', () => {
     expect(mockClient.start).toHaveBeenCalledWith(startOptions);
   });
 
+  it('merges bootstrap into startOptions when bootstrap is provided', () => {
+    const bootstrapData = { $flagsState: { flag: { variation: 0 } }, $valid: true };
+    createLDReactProvider('sdk-key', { kind: 'user', key: 'u1' }, { bootstrap: bootstrapData });
+
+    expect(mockClient.start).toHaveBeenCalledWith({ bootstrap: bootstrapData });
+  });
+
+  it('merges bootstrap with existing startOptions', () => {
+    const bootstrapData = { $flagsState: { flag: { variation: 0 } }, $valid: true };
+    const startOptions = { timeout: 5 };
+    createLDReactProvider(
+      'sdk-key',
+      { kind: 'user', key: 'u1' },
+      { startOptions, bootstrap: bootstrapData },
+    );
+
+    expect(mockClient.start).toHaveBeenCalledWith({ timeout: 5, bootstrap: bootstrapData });
+  });
+
+  it('does not merge bootstrap into startOptions when bootstrap is not provided', () => {
+    createLDReactProvider('sdk-key', { kind: 'user', key: 'u1' });
+
+    expect(mockClient.start).toHaveBeenCalledWith(undefined);
+  });
+
   it('uses provided reactContext option', () => {
     const CustomContext = initLDReactContext();
     const contextValues: LDReactClientContextValue[] = [];

packages/sdk/react/src/client/LDOptions.ts

@@ -70,4 +70,17 @@ export interface LDReactProviderOptions {
    * @returns {LDReactClientContext} The react context for the LaunchDarkly client.
    */
   reactContext?: LDReactClientContext;
+
+  /**
+   * Bootstrap data from the server. Pass the result of `flagsState.toJSON()` obtained
+   * from the server SDK's `allFlagsState` method.
+   *
+   * When provided, the client immediately uses these values before the first network
+   * response arrives — eliminating the flag-fetch waterfall on page load.
+   *
+   * This is merged into `startOptions.bootstrap` when the client is started. If both
+   * `bootstrap` and `startOptions.bootstrap` are provided, this top-level value takes
+   * precedence.
+   */
+  bootstrap?: unknown;
 }

packages/sdk/react/src/client/provider/LDReactProvider.tsx

@@ -120,12 +120,13 @@ export function createLDReactProvider(
   context: LDContext,
   options?: LDReactProviderOptions,
 ): React.FC<{ children: React.ReactNode }> {
-  const { deferInitialization, startOptions, reactContext, ldOptions } = options ?? {};
+  const { deferInitialization, startOptions, reactContext, ldOptions, bootstrap } = options ?? {};
 
   const client = createClient(clientSideID, context, ldOptions);
 
   if (!deferInitialization) {
-    client.start(startOptions);
+    const effectiveStartOptions = bootstrap ? { ...startOptions, bootstrap } : startOptions;
+    client.start(effectiveStartOptions);
   }
 
   return createLDReactProviderWithClient(client, reactContext);

packages/sdk/react/temp_docs/MIGRATING.md

@@ -179,6 +179,36 @@ state when initialization completes or when `client.identify()` is called.
 
 ---
 
+## Bootstrap
+
+### Old SDK
+
+Bootstrap data was passed nested inside `options`:
+
+```tsx
+// HOC
+withLDProvider({ clientSideID: 'your-id', options: { bootstrap: myData } })(App);
+
+// Async HOC
+const LDProvider = await asyncWithLDProvider({ clientSideID: 'your-id', options: { bootstrap: myData } });
+```
+
+### New SDK
+
+Bootstrap is a first-class option on `createLDReactProvider`:
+
+```tsx
+import { createLDReactProvider } from '@launchdarkly/react-sdk';
+
+const LDProvider = createLDReactProvider('your-client-side-id', { kind: 'user', key: 'user-key' }, {
+  bootstrap: myData,
+});
+```
+
+The `bootstrap` data format is unchanged from the old SDK. You can pass either a plain key-value
+object (`{ 'my-flag': true }`) or the output of `allFlagsState().toJSON()`, which includes
+`$flagsState` and `$valid` metadata.
+
 ## Removed APIs
 
 | Old API | Status | Replacement |