chore: adding deprecated flag hooks (#1166)

**Requirements**

- [x] I have added test coverage for new or changed functionality
- [x] I have followed the repository's [pull request submission
guidelines](../blob/main/CONTRIBUTING.md#submitting-pull-requests)
- [x] I have validated my changes against all supported platform
versions

**Related issues**

sdk-1993

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Introduces a new exported hook with Proxy-based evaluation behavior
that can affect runtime performance and event emission semantics for
consumers; changes are covered by targeted unit tests and are otherwise
additive.
> 
> **Overview**
> Adds a **deprecated** `useFlags` hook to the React SDK, exposing all
current flag values while wrapping them in a proxy that triggers
`client.variation` on each flag read (with per-key caching) so
evaluation events are recorded, and re-creating the proxy on
context/identity changes.
> 
> Exports the new hook from `client/index.ts`, adds Jest coverage for
subscription/unsubscription, re-render behavior, deprecation warning
logging, proxy caching semantics, and cache reset on context changes,
and hardens `contract-tests/open-browser.mjs` by retrying `page.goto` to
avoid startup race conditions.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
732bd27. 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/1166"
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

@@ -0,0 +1,37 @@
+import React from 'react';
+
+import { LDReactClientContextValue } from '../../../src/client/LDClient';
+import { LDReactContext } from '../../../src/client/provider/LDReactContext';
+import { makeMockClient } from '../mockClient';
+
+export function makeWrapper(mockClient: ReturnType<typeof makeMockClient>) {
+  const contextValue: LDReactClientContextValue = {
+    client: mockClient,
+    initializedState: 'unknown',
+  };
+
+  return function Wrapper({ children }: { children: React.ReactNode }) {
+    return <LDReactContext.Provider value={contextValue}>{children}</LDReactContext.Provider>;
+  };
+}
+
+/**
+ * Creates a wrapper whose context value can be updated after render.
+ * `setterRef.current` is set on first render and can be called inside `act()`.
+ */
+export function makeStatefulWrapper(mockClient: ReturnType<typeof makeMockClient>) {
+  const setterRef = {
+    current: null as React.Dispatch<React.SetStateAction<LDReactClientContextValue>> | null,
+  };
+
+  function Wrapper({ children }: { children: React.ReactNode }) {
+    const [ctxValue, setCtx] = React.useState<LDReactClientContextValue>({
+      client: mockClient,
+      initializedState: 'complete',
+    });
+    setterRef.current = setCtx;
+    return <LDReactContext.Provider value={ctxValue}>{children}</LDReactContext.Provider>;
+  }
+
+  return { Wrapper, setterRef };
+}

packages/sdk/react/__tests__/client/deprecated-hooks/useFlags.test.tsx

@@ -0,0 +1,223 @@
+/**
+ * @jest-environment jsdom
+ */
+import { act, render } from '@testing-library/react';
+import React from 'react';
+
+import { useFlags } from '../../../src/client/deprecated-hooks/useFlags';
+import { makeMockClient } from '../mockClient';
+import { makeStatefulWrapper, makeWrapper } from './renderHelpers';
+
+function FlagsConsumer({ onFlags }: { onFlags: (flags: Record<string, unknown>) => void }) {
+  const flags = useFlags();
+  onFlags(flags);
+  return <span data-testid="output">{JSON.stringify(flags)}</span>;
+}
+
+it('returns initial flag values from client.allFlags()', () => {
+  const mockClient = makeMockClient();
+  (mockClient.allFlags as jest.Mock).mockReturnValue({ 'my-flag': true });
+
+  const captured: Record<string, unknown>[] = [];
+
+  const Wrapper = makeWrapper(mockClient);
+  render(
+    <Wrapper>
+      <FlagsConsumer onFlags={(f) => captured.push(f)} />
+    </Wrapper>,
+  );
+
+  expect(captured[0]).toEqual({ 'my-flag': true });
+});
+
+it('subscribes to change event on mount and unsubscribes on unmount', () => {
+  const mockClient = makeMockClient();
+
+  const Wrapper = makeWrapper(mockClient);
+  const { unmount } = render(
+    <Wrapper>
+      <FlagsConsumer onFlags={() => {}} />
+    </Wrapper>,
+  );
+
+  expect(mockClient.on).toHaveBeenCalledWith('change', expect.any(Function));
+
+  const onCall = (mockClient.on as jest.Mock).mock.calls.find(
+    ([event]: [string]) => event === 'change',
+  );
+  const handler = onCall?.[1];
+
+  unmount();
+
+  expect(mockClient.off).toHaveBeenCalledWith('change', handler);
+});
+
+it('re-renders with new flags when change event fires', async () => {
+  const mockClient = makeMockClient();
+  (mockClient.allFlags as jest.Mock).mockReturnValue({ 'flag-a': false });
+
+  const captured: Record<string, unknown>[] = [];
+
+  const Wrapper = makeWrapper(mockClient);
+  render(
+    <Wrapper>
+      <FlagsConsumer onFlags={(f) => captured.push(f)} />
+    </Wrapper>,
+  );
+
+  expect(captured[captured.length - 1]).toEqual({ 'flag-a': false });
+
+  (mockClient.allFlags as jest.Mock).mockReturnValue({ 'flag-a': true });
+
+  await act(async () => {
+    mockClient.emitChange();
+  });
+
+  expect(captured[captured.length - 1]).toEqual({ 'flag-a': true });
+});
+
+it('logs a deprecation warning on mount via client.logger.warn', async () => {
+  const mockClient = makeMockClient();
+  const Wrapper = makeWrapper(mockClient);
+
+  function FlagConsumer() {
+    useFlags();
+    return null;
+  }
+
+  await act(async () => {
+    render(
+      <Wrapper>
+        <FlagConsumer />
+      </Wrapper>,
+    );
+  });
+
+  expect(mockClient.logger.warn).toHaveBeenCalledWith(
+    expect.stringContaining('[LaunchDarkly] useFlags is deprecated'),
+  );
+});
+
+it('clears the variation cache when the context changes after identify', () => {
+  const mockClient = makeMockClient();
+  (mockClient.allFlags as jest.Mock).mockReturnValue({ 'my-flag': true });
+
+  const { Wrapper: StatefulWrapper, setterRef } = makeStatefulWrapper(mockClient);
+
+  let capturedFlags: Record<string, unknown> = {};
+
+  function FlagReader() {
+    capturedFlags = useFlags();
+    return null;
+  }
+
+  render(
+    <StatefulWrapper>
+      <FlagReader />
+    </StatefulWrapper>,
+  );
+
+  // Read the flag to prime the variation cache
+  // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+  capturedFlags['my-flag'];
+  const callsBefore = (mockClient.variation as jest.Mock).mock.calls.length;
+
+  // Simulate context change (e.g. after identify)
+  act(() => {
+    setterRef.current!({
+      client: mockClient,
+      context: { kind: 'user', key: 'new-user' },
+      initializedState: 'complete',
+    });
+  });
+
+  // Reading the same key again should call variation again (cache was cleared)
+  // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+  capturedFlags['my-flag'];
+  expect((mockClient.variation as jest.Mock).mock.calls.length).toBeGreaterThan(callsBefore);
+});
+
+it('calls client.variation when reading a flag value from the returned object', () => {
+  const mockClient = makeMockClient();
+  (mockClient.allFlags as jest.Mock).mockReturnValue({ 'my-flag': true });
+
+  let capturedFlags: Record<string, unknown> = {};
+
+  function FlagReader() {
+    capturedFlags = useFlags();
+    return null;
+  }
+
+  const Wrapper = makeWrapper(mockClient);
+  render(
+    <Wrapper>
+      <FlagReader />
+    </Wrapper>,
+  );
+
+  // Reading a flag through the proxy should call variation, not just return the allFlags value
+  const value = capturedFlags['my-flag'];
+  expect(mockClient.variation).toHaveBeenCalledWith('my-flag', true);
+  expect(value).toBe(true);
+});
+
+it('calls client.variation only once per flag key when the same key is read multiple times', () => {
+  const mockClient = makeMockClient();
+  (mockClient.allFlags as jest.Mock).mockReturnValue({ 'my-flag': true });
+
+  let capturedFlags: Record<string, unknown> = {};
+
+  function FlagReader() {
+    capturedFlags = useFlags();
+    return null;
+  }
+
+  const Wrapper = makeWrapper(mockClient);
+  render(
+    <Wrapper>
+      <FlagReader />
+    </Wrapper>,
+  );
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+  capturedFlags['my-flag'];
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+  capturedFlags['my-flag'];
+
+  const calls = (mockClient.variation as jest.Mock).mock.calls.filter(
+    ([key]: [string]) => key === 'my-flag',
+  );
+  expect(calls).toHaveLength(1);
+});
+
+it('does not re-render when a different key changes', async () => {
+  const mockClient = makeMockClient();
+  (mockClient.allFlags as jest.Mock).mockReturnValue({ 'flag-a': false, 'flag-b': false });
+
+  let renderCount = 0;
+
+  function CountingConsumer() {
+    const flags = useFlags();
+    renderCount += 1;
+    return <span>{JSON.stringify(flags)}</span>;
+  }
+
+  const Wrapper = makeWrapper(mockClient);
+  render(
+    <Wrapper>
+      <CountingConsumer />
+    </Wrapper>,
+  );
+
+  const initialRenders = renderCount;
+
+  // useFlags subscribes to 'change' (all flags), so any flag change triggers re-render.
+  // This test verifies that flag-specific change (change:flag-b) does NOT trigger useFlags.
+  await act(async () => {
+    mockClient.emitFlagChange('flag-b');
+  });
+
+  // 'change:flag-b' should not trigger the 'change' handler used by useFlags
+  expect(renderCount).toBe(initialRenders);
+});

packages/sdk/react/contract-tests/open-browser.mjs

@@ -38,7 +38,19 @@ page.on('pageerror', (error) => {
   console.error(`[Browser Error] ${error.message}`);
 });
 
-await page.goto(url);
+// Retry page.goto until the entity is ready (race-condition guard)
+const maxRetries = 15;
+const retryDelayMs = 2000;
+for (let attempt = 1; attempt <= maxRetries; attempt++) {
+  try {
+    await page.goto(url);
+    break;
+  } catch (err) {
+    if (attempt === maxRetries) throw err;
+    console.log(`[Browser] Connection to ${url} failed (attempt ${attempt}/${maxRetries}), retrying in ${retryDelayMs}ms...`);
+    await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+  }
+}
 
 console.log('Browser is open and running. Press Ctrl+C to close.');
 

packages/sdk/react/src/client/deprecated-hooks/index.ts

@@ -0,0 +1 @@
+export { useFlags } from './useFlags';

packages/sdk/react/src/client/deprecated-hooks/useFlags.ts

@@ -0,0 +1,81 @@
+'use client';
+
+import { useContext, useEffect, useMemo, useState } from 'react';
+
+import type { LDFlagSet } from '@launchdarkly/js-client-sdk';
+
+import type { LDReactClient, LDReactClientContextValue } from '../LDClient';
+import { LDReactContext } from '../provider/LDReactContext';
+
+function toFlagsProxy<T extends LDFlagSet>(client: LDReactClient, flags: T): T {
+  // Cache the results of the variation calls to avoid redundant calls.
+  // Note that this function is memoized, so when the context changes, the
+  // cache is recreated.
+
+  // There is still an potential issue here if this function is used to only evaluate a
+  // small subset of flags. In this case, any flag updates will cause a reset of the cache.
+  // It is recommended to use the typed variation hooks (useBoolVariation, useStringVariation,
+  // useNumberVariation, useJsonVariation) for better performance when reading a subset of flags.
+  const cache = new Map<string, unknown>();
+
+  return new Proxy(flags, {
+    get(target, prop, receiver) {
+      const currentValue = Reflect.get(target, prop, receiver);
+
+      // Pass through symbols and non-flag keys (e.g. Object prototype methods)
+      if (typeof prop === 'symbol' || !Object.prototype.hasOwnProperty.call(target, prop)) {
+        return currentValue;
+      }
+
+      if (currentValue === undefined) {
+        return undefined;
+      }
+
+      if (cache.has(prop)) {
+        return cache.get(prop);
+      }
+
+      // Trigger a variation call so LaunchDarkly records an evaluation event
+      const result = client.variation(prop as string, currentValue);
+      cache.set(prop, result);
+      return result;
+    },
+  });
+}
+
+/**
+ * Returns all feature flags for the current context. Re-renders whenever any flag value changes.
+ * Flag values are accessed via a proxy that triggers a `variation` call on each read, ensuring
+ * evaluation events are sent to LaunchDarkly for accurate usage metrics.
+ *
+ * @param reactContext Optional React context to read from. Defaults to the global `LDReactContext`.
+ * @returns All current flag values as `T`, wrapped in a proxy that records evaluations.
+ *
+ * @deprecated This hook is provided to ease migration from older versions of the React SDK.
+ * For better performance, migrate to the typed variation hooks (`useBoolVariation`,
+ * `useStringVariation`, `useNumberVariation`, `useJsonVariation`) or use `useLDClient`
+ * with the client's `allFlags` method directly. This hook will be removed in a future major version.
+ */
+export function useFlags<T extends LDFlagSet = LDFlagSet>(
+  reactContext?: React.Context<LDReactClientContextValue>,
+): T {
+  const { client, context } = useContext(reactContext ?? LDReactContext);
+
+  useEffect(() => {
+    client.logger.warn(
+      '[LaunchDarkly] useFlags is deprecated and will be removed in a future major version.',
+    );
+  }, []);
+
+  const [flags, setFlags] = useState<T>(() => client.allFlags() as T);
+
+  useEffect(() => {
+    const handler = () => setFlags(client.allFlags() as T);
+    client.on('change', handler);
+    return () => client.off('change', handler);
+  }, [client]);
+
+  // context is included so the proxy is recreated on every identity change,
+  // ensuring variation is re-called for the new LaunchDarkly context.
+  return useMemo(() => toFlagsProxy(client, flags), [client, flags, context]) as T;
+}

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

@@ -6,4 +6,5 @@ export * from './provider/LDReactContext';
 export { createLDReactProvider, createLDReactProviderWithClient } from './provider/LDReactProvider';
 export { createClient } from './LDReactClient';
 
+export * from './deprecated-hooks';
 export * from './hooks';