chore: refactoring react server component client (#1186)

This PR is to finalize how the react server components can access server
side LDClient. A few key points:
- Developers will spin up a "ld server session" which is a wrapper
around the global server sdk (which should be separately managed) on
every request session. This wrapper would provide some React-esque
capabilities to the underlying sdk.
- This sdk session will be encapsulated in a [react
cache](https://react.dev/reference/react/cache) which should be cleaned
after every request session.
- Developers can also manage these sessions themselves as we provide the
create wrapper function without having to deal with react cache.

This address:
SDK-2026
SDK-2021


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Moderate risk due to a breaking redesign of the server entrypoint API
(removing `createReactServerClient`/context-provider options and
changing browser behavior from no-op to throw), which could affect
existing integrations and bundling boundaries.
> 
> **Overview**
> Refactors the React SDK server entrypoint to use a **per-request
`LDServerSession`** (context bound at creation) stored in React
`cache()`, exposed via `createLDServerSession`/`useLDServerSession`, and
enforces server-only usage by **throwing in browser environments**
rather than returning a no-op client.
> 
> Removes the previous `createReactServerClient` +
`LDContextProvider`/`LDReactServerOptions` API, introduces
`LDServerBaseClient` as a minimal structural interface, and updates
docs/examples accordingly. Adds Jest coverage for session
binding/caching behavior and adjusts build tooling to emit separate
client/server bundles (including a `"use client"` banner for the client
entry) plus small eslint/gitignore tweaks for examples.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
80eca87. 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/1186"
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/.eslintrc.cjs

@@ -1,5 +1,5 @@
 module.exports = {
-  ignorePatterns: ['contract-tests/next-env.d.ts'],
+  ignorePatterns: ['contract-tests/next-env.d.ts', 'examples/server-only/next-env.d.ts'],
   overrides: [
     {
       files: ['contract-tests/**/*.ts', 'contract-tests/**/*.tsx'],

packages/sdk/react/__tests__/server/createLDServerSession.test.ts

@@ -0,0 +1,177 @@
+import { LDContext, LDFlagsStateOptions } from '@launchdarkly/js-server-sdk-common';
+
+import { createLDServerSession, isServer } from '../../src/server/index';
+
+const context: LDContext = { kind: 'user', key: 'test-user' };
+
+function makeMockBaseClient() {
+  return {
+    initialized: jest.fn(() => true),
+    boolVariation: jest.fn((_key: string, _ctx: LDContext, def: boolean) => Promise.resolve(def)),
+    numberVariation: jest.fn((_key: string, _ctx: LDContext, def: number) => Promise.resolve(def)),
+    stringVariation: jest.fn((_key: string, _ctx: LDContext, def: string) => Promise.resolve(def)),
+    jsonVariation: jest.fn((_key: string, _ctx: LDContext, def: unknown) => Promise.resolve(def)),
+    boolVariationDetail: jest.fn((_key: string, _ctx: LDContext, def: boolean) =>
+      Promise.resolve({ value: def, variationIndex: null, reason: { kind: 'OFF' as const } }),
+    ),
+    numberVariationDetail: jest.fn((_key: string, _ctx: LDContext, def: number) =>
+      Promise.resolve({ value: def, variationIndex: null, reason: { kind: 'OFF' as const } }),
+    ),
+    stringVariationDetail: jest.fn((_key: string, _ctx: LDContext, def: string) =>
+      Promise.resolve({ value: def, variationIndex: null, reason: { kind: 'OFF' as const } }),
+    ),
+    jsonVariationDetail: jest.fn((_key: string, _ctx: LDContext, def: unknown) =>
+      Promise.resolve({ value: def, variationIndex: null, reason: { kind: 'OFF' as const } }),
+    ),
+    // @ts-ignore — mock return shape matches LDFlagsState structurally
+    allFlagsState: jest.fn((_context: LDContext, _options?: LDFlagsStateOptions) =>
+      Promise.resolve({
+        valid: true,
+        getFlagValue: jest.fn(),
+        getFlagReason: jest.fn(),
+        allValues: jest.fn(() => ({})),
+        toJSON: jest.fn(() => ({ $flagsState: {}, $valid: true })),
+      }),
+    ),
+  };
+}
+
+it('isServer() returns true in a Node test environment', () => {
+  expect(isServer()).toBe(true);
+});
+
+it('getContext() returns the context passed at creation', () => {
+  const client = makeMockBaseClient();
+  const session = createLDServerSession(client, context);
+  expect(session.getContext()).toEqual(context);
+});
+
+it('initialized() delegates to the base client', () => {
+  const client = makeMockBaseClient();
+  client.initialized.mockReturnValue(false);
+  const session = createLDServerSession(client, context);
+  expect(session.initialized()).toBe(false);
+  expect(client.initialized).toHaveBeenCalledTimes(1);
+});
+
+it('boolVariation() calls base client with bound context', async () => {
+  const client = makeMockBaseClient();
+  client.boolVariation.mockResolvedValue(true);
+  const session = createLDServerSession(client, context);
+  const result = await session.boolVariation('my-flag', false);
+  expect(result).toBe(true);
+  expect(client.boolVariation).toHaveBeenCalledWith('my-flag', context, false);
+});
+
+it('numberVariation() calls base client with bound context', async () => {
+  const client = makeMockBaseClient();
+  client.numberVariation.mockResolvedValue(42);
+  const session = createLDServerSession(client, context);
+  const result = await session.numberVariation('my-flag', 0);
+  expect(result).toBe(42);
+  expect(client.numberVariation).toHaveBeenCalledWith('my-flag', context, 0);
+});
+
+it('stringVariation() calls base client with bound context', async () => {
+  const client = makeMockBaseClient();
+  client.stringVariation.mockResolvedValue('hello');
+  const session = createLDServerSession(client, context);
+  const result = await session.stringVariation('my-flag', 'default');
+  expect(result).toBe('hello');
+  expect(client.stringVariation).toHaveBeenCalledWith('my-flag', context, 'default');
+});
+
+it('jsonVariation() calls base client with bound context', async () => {
+  const client = makeMockBaseClient();
+  const json = { key: 'value' };
+  client.jsonVariation.mockResolvedValue(json);
+  const session = createLDServerSession(client, context);
+  const result = await session.jsonVariation('my-flag', {});
+  expect(result).toEqual(json);
+  expect(client.jsonVariation).toHaveBeenCalledWith('my-flag', context, {});
+});
+
+it('boolVariationDetail() calls base client with bound context', async () => {
+  const client = makeMockBaseClient();
+  const detail = { value: true, variationIndex: 1, reason: { kind: 'RULE_MATCH' as const } };
+  // @ts-ignore — valid LDEvaluationDetailTyped<boolean> shape; mock type is too narrow
+  client.boolVariationDetail.mockResolvedValue(detail);
+  const session = createLDServerSession(client, context);
+  const result = await session.boolVariationDetail('my-flag', false);
+  expect(result).toEqual(detail);
+  expect(client.boolVariationDetail).toHaveBeenCalledWith('my-flag', context, false);
+});
+
+it('numberVariationDetail() calls base client with bound context', async () => {
+  const client = makeMockBaseClient();
+  const detail = { value: 42, variationIndex: 1, reason: { kind: 'RULE_MATCH' as const } };
+  // @ts-ignore — valid LDEvaluationDetailTyped<number> shape; mock type is too narrow
+  client.numberVariationDetail.mockResolvedValue(detail);
+  const session = createLDServerSession(client, context);
+  const result = await session.numberVariationDetail('my-flag', 0);
+  expect(result).toEqual(detail);
+  expect(client.numberVariationDetail).toHaveBeenCalledWith('my-flag', context, 0);
+});
+
+it('stringVariationDetail() calls base client with bound context', async () => {
+  const client = makeMockBaseClient();
+  const detail = { value: 'hello', variationIndex: 1, reason: { kind: 'RULE_MATCH' as const } };
+  // @ts-ignore — valid LDEvaluationDetailTyped<string> shape; mock type is too narrow
+  client.stringVariationDetail.mockResolvedValue(detail);
+  const session = createLDServerSession(client, context);
+  const result = await session.stringVariationDetail('my-flag', 'default');
+  expect(result).toEqual(detail);
+  expect(client.stringVariationDetail).toHaveBeenCalledWith('my-flag', context, 'default');
+});
+
+it('jsonVariationDetail() calls base client with bound context', async () => {
+  const client = makeMockBaseClient();
+  const detail = {
+    value: { key: 'value' },
+    variationIndex: 1,
+    reason: { kind: 'RULE_MATCH' as const },
+  };
+  // @ts-ignore — valid LDEvaluationDetailTyped<unknown> shape; mock type is too narrow
+  client.jsonVariationDetail.mockResolvedValue(detail);
+  const session = createLDServerSession(client, context);
+  const result = await session.jsonVariationDetail('my-flag', {});
+  expect(result).toEqual(detail);
+  expect(client.jsonVariationDetail).toHaveBeenCalledWith('my-flag', context, {});
+});
+
+it('allFlagsState() calls base client with bound context', async () => {
+  const client = makeMockBaseClient();
+  const session = createLDServerSession(client, context);
+  await session.allFlagsState();
+  expect(client.allFlagsState).toHaveBeenCalledWith(context, undefined);
+});
+
+it('allFlagsState() forwards options to base client', async () => {
+  const client = makeMockBaseClient();
+  const session = createLDServerSession(client, context);
+  const options = { clientSideOnly: true };
+  await session.allFlagsState(options);
+  expect(client.allFlagsState).toHaveBeenCalledWith(context, options);
+});
+
+describe('given a browser environment (window defined)', () => {
+  let originalWindow: typeof globalThis.window;
+
+  beforeEach(() => {
+    originalWindow = globalThis.window;
+    // @ts-ignore
+    globalThis.window = {};
+  });
+
+  afterEach(() => {
+    // @ts-ignore
+    globalThis.window = originalWindow;
+  });
+
+  it('throws an error instead of returning a no-op session', () => {
+    const client = makeMockBaseClient();
+    expect(() => createLDServerSession(client, context)).toThrow(
+      'createLDServerWrapper must only be called on the server.',
+    );
+  });
+});

packages/sdk/react/__tests__/server/useLDServerSession.test.ts

@@ -0,0 +1,62 @@
+import { LDContext } from '@launchdarkly/js-server-sdk-common';
+
+import { createLDServerSession, useLDServerSession } from '../../src/server/index';
+import type { LDServerSession } from '../../src/server/LDClient';
+
+// The `mock` prefix is required so ts-jest's hoist plugin allows this variable
+// to be referenced inside the jest.mock() factory below.
+let mockCacheStore: { session: LDServerSession | null } = { session: null };
+
+jest.mock('react', () => ({
+  cache: (_fn: unknown) => () => mockCacheStore,
+}));
+
+beforeEach(() => {
+  mockCacheStore = { session: null };
+});
+
+it('useLDServerSession() returns null when no session has been stored', () => {
+  const result = useLDServerSession();
+  expect(result).toBeNull();
+});
+
+it('useLDServerSession() returns the session stored by createLDServerSession()', () => {
+  const context: LDContext = { kind: 'user', key: 'test-user' };
+  const client = {
+    initialized: jest.fn(() => true),
+    boolVariation: jest.fn(),
+    numberVariation: jest.fn(),
+    stringVariation: jest.fn(),
+    jsonVariation: jest.fn(),
+    boolVariationDetail: jest.fn(),
+    numberVariationDetail: jest.fn(),
+    stringVariationDetail: jest.fn(),
+    jsonVariationDetail: jest.fn(),
+    allFlagsState: jest.fn(),
+  };
+  // @ts-ignore — minimal mock satisfies LDServerBaseClient structurally
+  const session = createLDServerSession(client, context);
+  const result = useLDServerSession();
+  expect(result).toBe(session);
+});
+
+describe('given a browser environment (window defined)', () => {
+  let originalWindow: typeof globalThis.window;
+
+  beforeEach(() => {
+    originalWindow = globalThis.window;
+    // @ts-ignore
+    globalThis.window = {};
+  });
+
+  afterEach(() => {
+    // @ts-ignore
+    globalThis.window = originalWindow;
+  });
+
+  it('throws when called in a browser environment', () => {
+    expect(() => useLDServerSession()).toThrow(
+      'useLDServerSession must only be called on the server',
+    );
+  });
+});

packages/sdk/react/examples/.gitignore

@@ -0,0 +1,3 @@
+# Temporary ignore to keep PRs manageable.
+
+server-only