fix(react-sdk): double evaluation on client side init (#1229)

<!-- CURSOR_SUMMARY -->
> [!NOTE]
> **Medium Risk**
> Changes how variation hooks evaluate flags by introducing readiness
gating via a new `LDReactClient.isReady()` API, which could affect
initial render values and evaluation timing across apps (especially
around bootstrap/initialization transitions). Test coverage was
expanded, but behavior changes are user-visible.
> 
> **Overview**
> Prevents variation hooks from evaluating flags before the client is
ready, avoiding extra/double evaluations during initialization.
`useVariationCore` now returns the default (or a caller-provided
not-ready default) until `client.isReady()` becomes true, then evaluates
once and continues to re-evaluate on context/key changes and
`change:<flag>` events.
> 
> Adds `LDReactClient.isReady()` (implemented in `createClient`,
including bootstrap awareness, and in the server-side noop client) and
updates variation *detail* hooks to return a `CLIENT_NOT_READY`
evaluation reason when gated. Tests and mocks are updated accordingly,
and the client-only example UI now hides flag output until
initialization completes.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
f401bc0. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

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

---

<a href="https://app.devin.ai/review/launchdarkly/js-core/pull/1229"
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 -->

Author: joker23

packages/sdk/react/__tests__/client/deprecated-hooks/renderHelpers.tsx

@@ -10,7 +10,7 @@ export function makeWrapper(
 ) {
   const contextValue: LDReactClientContextValue = {
     client: mockClient,
-    initializedState: 'initializing',
+    initializedState: 'complete',
     ...contextOverrides,
   };
 

packages/sdk/react/__tests__/client/hooks/useVariation.test.tsx

@@ -20,7 +20,7 @@ function makeWrapper(
 ) {
   const contextValue: LDReactClientContextValue = {
     client: mockClient,
-    initializedState: 'initializing',
+    initializedState: 'complete',
     ...contextOverrides,
   };
 
@@ -563,3 +563,135 @@ it('useJsonVariation calls variation again when context changes', () => {
 
   expect((mockClient.jsonVariation as jest.Mock).mock.calls.length).toBeGreaterThan(callsBefore);
 });
+
+// ─── ready-gating tests ──────────────────────────────────────────────────────
+
+it('does not call variation when not ready', () => {
+  const mockClient = makeMockClient();
+  (mockClient.isReady as jest.Mock).mockReturnValue(false);
+
+  function FlagConsumer() {
+    useBoolVariation('my-flag', false);
+    return null;
+  }
+
+  const Wrapper = makeWrapper(mockClient, { initializedState: 'initializing' });
+  render(
+    <Wrapper>
+      <FlagConsumer />
+    </Wrapper>,
+  );
+
+  expect(mockClient.boolVariation).not.toHaveBeenCalled();
+});
+
+it('returns defaultValue when not ready', () => {
+  const mockClient = makeMockClient();
+  (mockClient.isReady as jest.Mock).mockReturnValue(false);
+  (mockClient.boolVariation as jest.Mock).mockReturnValue(true);
+
+  const captured: boolean[] = [];
+
+  function FlagConsumer() {
+    const value = useBoolVariation('my-flag', false);
+    captured.push(value);
+    return null;
+  }
+
+  const Wrapper = makeWrapper(mockClient, { initializedState: 'initializing' });
+  render(
+    <Wrapper>
+      <FlagConsumer />
+    </Wrapper>,
+  );
+
+  expect(captured[0]).toBe(false);
+});
+
+it('evaluates once when initialization completes', () => {
+  const mockClient = makeMockClient();
+  (mockClient.isReady as jest.Mock).mockReturnValue(false);
+  (mockClient.boolVariation as jest.Mock).mockReturnValue(true);
+
+  let setContextValue!: React.Dispatch<React.SetStateAction<LDReactClientContextValue>>;
+  const captured: boolean[] = [];
+
+  function StatefulWrapper({ children }: { children: React.ReactNode }) {
+    const [ctxValue, setCtx] = React.useState<LDReactClientContextValue>({
+      client: mockClient,
+      initializedState: 'initializing',
+    });
+    setContextValue = setCtx;
+    return <LDReactContext.Provider value={ctxValue}>{children}</LDReactContext.Provider>;
+  }
+
+  function FlagConsumer() {
+    const value = useBoolVariation('my-flag', false);
+    captured.push(value);
+    return null;
+  }
+
+  render(
+    <StatefulWrapper>
+      <FlagConsumer />
+    </StatefulWrapper>,
+  );
+
+  expect(mockClient.boolVariation).not.toHaveBeenCalled();
+  expect(captured[captured.length - 1]).toBe(false);
+
+  (mockClient.isReady as jest.Mock).mockReturnValue(true);
+
+  act(() => {
+    setContextValue({
+      client: mockClient,
+      initializedState: 'complete',
+      context: { kind: 'user', key: 'user-1' },
+    });
+  });
+
+  expect(mockClient.boolVariation).toHaveBeenCalledTimes(1);
+  expect(captured[captured.length - 1]).toBe(true);
+});
+
+it('evaluates exactly once on mount when already initialized (bootstrap)', () => {
+  const mockClient = makeMockClient();
+  (mockClient.boolVariation as jest.Mock).mockReturnValue(true);
+
+  function FlagConsumer() {
+    useBoolVariation('my-flag', false);
+    return null;
+  }
+
+  const Wrapper = makeWrapper(mockClient, { initializedState: 'complete' });
+  render(
+    <Wrapper>
+      <FlagConsumer />
+    </Wrapper>,
+  );
+
+  expect(mockClient.boolVariation).toHaveBeenCalledTimes(1);
+});
+
+it('evaluates when initialization failed (client returns defaults on failure)', () => {
+  const mockClient = makeMockClient();
+  (mockClient.boolVariation as jest.Mock).mockReturnValue(false);
+
+  const captured: boolean[] = [];
+
+  function FlagConsumer() {
+    const value = useBoolVariation('my-flag', false);
+    captured.push(value);
+    return null;
+  }
+
+  const Wrapper = makeWrapper(mockClient, { initializedState: 'failed' });
+  render(
+    <Wrapper>
+      <FlagConsumer />
+    </Wrapper>,
+  );
+
+  expect(mockClient.boolVariation).toHaveBeenCalledTimes(1);
+  expect(captured[0]).toBe(false);
+});

packages/sdk/react/__tests__/client/hooks/useVariationDetail.test.tsx

@@ -19,7 +19,7 @@ import { makeMockClient } from '../mockClient';
 function makeWrapper(mockClient: ReturnType<typeof makeMockClient>) {
   const contextValue: LDReactClientContextValue = {
     client: mockClient,
-    initializedState: 'initializing',
+    initializedState: 'complete',
   };
 
   return function Wrapper({ children }: { children: React.ReactNode }) {

packages/sdk/react/__tests__/client/mockClient.ts

@@ -88,6 +88,7 @@ export function makeMockClient(options: MockClientOptions = {}): MockClient {
     // @ts-ignore
     waitForInitialization: jest.fn(() => Promise.resolve({ status: 'complete' as const })),
     addHook: jest.fn(),
+    isReady: jest.fn(() => true),
     shouldUseCamelCaseFlagKeys: jest.fn(() => true),
   } as unknown as LDReactClient;
 

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

@@ -167,6 +167,66 @@ it('includes error in initial state when client was already failed before mount'
   expect(firstRender?.error).toBe(preFailedError);
 });
 
+it('initializedState is complete when client is already initialized at mount (bootstrap)', () => {
+  const client = makeMockClient({ initialState: 'complete' });
+  const contextValues: LDReactClientContextValue[] = [];
+
+  function Consumer() {
+    const value = useContext(LDReactContext);
+    contextValues.push(value);
+    return null;
+  }
+
+  const Provider = createLDReactProviderWithClient(client);
+
+  render(
+    <Provider>
+      <Consumer />
+    </Provider>,
+  );
+
+  expect(contextValues[0]?.initializedState).toBe('complete');
+});
+
+it('initializedState stays complete after context changes from identify', async () => {
+  const client = makeMockClient();
+  const contextValues: LDReactClientContextValue[] = [];
+
+  function Consumer() {
+    const value = useContext(LDReactContext);
+    contextValues.push(value);
+    return null;
+  }
+
+  const Provider = createLDReactProviderWithClient(client);
+
+  render(
+    <Provider>
+      <Consumer />
+    </Provider>,
+  );
+
+  await act(async () => {
+    client.fireInitStatusChange('complete');
+  });
+
+  await waitFor(() => {
+    expect(contextValues[contextValues.length - 1]?.initializedState).toBe('complete');
+  });
+
+  await act(async () => {
+    client.fireContextChange({ kind: 'user', key: 'new-user' });
+  });
+
+  await waitFor(() => {
+    expect(contextValues[contextValues.length - 1]?.context).toEqual({
+      kind: 'user',
+      key: 'new-user',
+    });
+  });
+  expect(contextValues[contextValues.length - 1]?.initializedState).toBe('complete');
+});
+
 // ─── createLDReactProvider (convenience factory) ─────────────────────────────
 
 describe('createLDReactProvider (convenience factory)', () => {

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

@@ -16,8 +16,8 @@ it('useBoolVariation reads from each respective client when using separate conte
   const ContextA = initLDReactContext();
   const ContextB = initLDReactContext();
 
-  const clientA = makeMockClient();
-  const clientB = makeMockClient();
+  const clientA = makeMockClient({ initialState: 'complete' });
+  const clientB = makeMockClient({ initialState: 'complete' });
 
   (clientA.boolVariation as jest.Mock).mockReturnValue(true);
   (clientB.boolVariation as jest.Mock).mockReturnValue(false);
@@ -52,8 +52,8 @@ it('useBoolVariation calls boolVariation on the correct client for each context'
   const ContextA = initLDReactContext();
   const ContextB = initLDReactContext();
 
-  const clientA = makeMockClient();
-  const clientB = makeMockClient();
+  const clientA = makeMockClient({ initialState: 'complete' });
+  const clientB = makeMockClient({ initialState: 'complete' });
 
   (clientA.boolVariation as jest.Mock).mockReturnValue(true);
   (clientB.boolVariation as jest.Mock).mockReturnValue(false);
@@ -88,8 +88,8 @@ it('useLDClient returns the respective client for each context', () => {
   const ContextA = initLDReactContext();
   const ContextB = initLDReactContext();
 
-  const clientA = makeMockClient();
-  const clientB = makeMockClient();
+  const clientA = makeMockClient({ initialState: 'complete' });
+  const clientB = makeMockClient({ initialState: 'complete' });
 
   const ProviderA = createLDReactProviderWithClient(clientA, ContextA);
   const ProviderB = createLDReactProviderWithClient(clientB, ContextB);

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

@@ -14,8 +14,8 @@ import { makeMockClient } from '../mockClient';
 it('hook using a named context reads from the named client, not the global one', () => {
   const NamedContext = initLDReactContext();
 
-  const globalClient = makeMockClient();
-  const namedClient = makeMockClient();
+  const globalClient = makeMockClient({ initialState: 'complete' });
+  const namedClient = makeMockClient({ initialState: 'complete' });
 
   (globalClient.boolVariation as jest.Mock).mockReturnValue(true);
   (namedClient.boolVariation as jest.Mock).mockReturnValue(false);
@@ -46,8 +46,8 @@ it('hook using a named context reads from the named client, not the global one',
 it('hook with no context arg reads from the global LDReactContext provider', () => {
   const NamedContext = initLDReactContext();
 
-  const globalClient = makeMockClient();
-  const namedClient = makeMockClient();
+  const globalClient = makeMockClient({ initialState: 'complete' });
+  const namedClient = makeMockClient({ initialState: 'complete' });
 
   (globalClient.boolVariation as jest.Mock).mockReturnValue(true);
   (namedClient.boolVariation as jest.Mock).mockReturnValue(false);
@@ -78,7 +78,7 @@ it('hook with no context arg reads from the global LDReactContext provider', ()
 it('a named-context provider does not populate the global LDReactContext', () => {
   const NamedContext = initLDReactContext();
 
-  const namedClient = makeMockClient();
+  const namedClient = makeMockClient({ initialState: 'complete' });
   const NamedProvider = createLDReactProviderWithClient(namedClient, NamedContext);
 
   let globalContextValue: LDReactClientContextValue | undefined;
@@ -102,8 +102,8 @@ it('a named-context provider does not populate the global LDReactContext', () =>
 it('useBoolVariation and useLDClient return data from the named context when supplied', () => {
   const NamedContext = initLDReactContext();
 
-  const globalClient = makeMockClient();
-  const namedClient = makeMockClient();
+  const globalClient = makeMockClient({ initialState: 'complete' });
+  const namedClient = makeMockClient({ initialState: 'complete' });
 
   (namedClient.boolVariation as jest.Mock).mockReturnValue(true);
   (globalClient.boolVariation as jest.Mock).mockReturnValue(false);

packages/sdk/react/examples/client-only/src/App.tsx

@@ -58,41 +58,46 @@ function App() {
     statusMessage = 'Initializing…';
   }
 
-  const headerBgColor = flagValue ? '#00844B' : '#373841';
+  const ready = status !== 'initializing';
+  const headerBgColor = ready && flagValue ? '#00844B' : '#373841';
 
   return (
     <div className="App">
       <header className="App-header" style={{ backgroundColor: headerBgColor }}>
-        <p>{statusMessage}</p>
-        <p>{`The ${flagKey} feature flag evaluates to ${flagValue ? 'true' : 'false'}.`}</p>
-        <form onSubmit={handleSubmit}>
-          <input
-            type="text"
-            value={inputValue}
-            onChange={(e) => setInputValue(e.target.value)}
-            placeholder="Flag key"
-            aria-label="Flag key"
-          />
-          <button type="submit">Update flag</button>
-        </form>
-        <div style={{ display: 'flex', gap: '8px' }}>
-          {PRESET_CONTEXTS.map((preset) => {
-            const isActive = activeContextKey === (preset.key as string);
-            return (
-              <button
-                key={preset.key as string}
-                onClick={() => handleSelectContext(preset)}
-                disabled={identifyPending}
-                style={{
-                  fontWeight: isActive ? 'bold' : 'normal',
-                  outline: isActive ? '2px solid white' : 'none',
-                }}
-              >
-                {preset.name as string}
-              </button>
-            );
-          })}
-        </div>
+        {ready && (
+          <>
+            <p>{statusMessage}</p>
+            <p>{`The ${flagKey} feature flag evaluates to ${flagValue ? 'true' : 'false'}.`}</p>
+            <form onSubmit={handleSubmit}>
+              <input
+                type="text"
+                value={inputValue}
+                onChange={(e) => setInputValue(e.target.value)}
+                placeholder="Flag key"
+                aria-label="Flag key"
+              />
+              <button type="submit">Update flag</button>
+            </form>
+            <div style={{ display: 'flex', gap: '8px' }}>
+              {PRESET_CONTEXTS.map((preset) => {
+                const isActive = activeContextKey === (preset.key as string);
+                return (
+                  <button
+                    key={preset.key as string}
+                    onClick={() => handleSelectContext(preset)}
+                    disabled={identifyPending}
+                    style={{
+                      fontWeight: isActive ? 'bold' : 'normal',
+                      outline: isActive ? '2px solid white' : 'none',
+                    }}
+                  >
+                    {preset.name as string}
+                  </button>
+                );
+              })}
+            </div>
+          </>
+        )}
       </header>
     </div>
   );