docs: fixing up documentation for release

joker23 · joker23 · commit e08abc5e01a6 · 2026-04-01T14:46:37.000-05:00
diff --git a/packages/sdk/react/README.md b/packages/sdk/react/README.md
@@ -16,6 +16,9 @@
 
 ☝️☝️☝️
 
+## Getting started
+Refer to the [SDK documentation](https://launchdarkly.com/docs/sdk/client-side/react/react-web#get-started) for instructions on getting started with using the SDK.
+
 ## About LaunchDarkly
 
 - LaunchDarkly is a continuous delivery platform that provides feature flags as a service and allows developers to iterate quickly and safely. We allow you to easily flag your features and manage them from the LaunchDarkly dashboard. With LaunchDarkly, you can:
diff --git a/packages/sdk/react/package.json b/packages/sdk/react/package.json
@@ -13,6 +13,7 @@
     "launchdarkly",
     "react",
     "isomorphic",
+    "react-server-components",
     "nextjs",
     "remix"
   ],
diff --git a/packages/sdk/react/src/client/LDClient.ts b/packages/sdk/react/src/client/LDClient.ts
@@ -59,7 +59,7 @@ export interface LDReactClient extends LDClient {
   /**
    * Returns whether the client is ready to evaluate flags. This is true when the client
    * has completed initialization (successfully or with failure), or when bootstrap data
-   * was provided (flags are available immediately via `presetFlags`).
+   * was provided.
    *
    * @returns {boolean} Whether the client can evaluate flags.
    */
@@ -68,8 +68,8 @@ export interface LDReactClient extends LDClient {
   /**
    * @internal
    *
-   * Returns whether flag keys should be converted to camelCase in `useFlags()` and resolved from camelCase
-   * in the individual variation hooks. Defaults to `true` when absent.
+   * Returns whether flag keys should be converted to camelCase in `useFlags()`.
+   * Defaults to `true` when absent.
    *
    * @remarks
    * **NOTE:** This method is only used by `useFlags()` hook.
diff --git a/packages/sdk/react/src/client/LDOptions.ts b/packages/sdk/react/src/client/LDOptions.ts
@@ -61,13 +61,11 @@ export interface LDReactProviderOptions {
   deferInitialization?: boolean;
 
   /**
-   * This option allow developers to provide their own named react context for
-   * the launchdarkly client. This is useful for cases where you want to have multiple
+   * This option allows developers to provide their own named react context for
+   * the LaunchDarkly client. This is useful for cases where you want to have multiple
    * clients in the same application. If not provided, the default context will be used.
    *
-   * @see {@link LDReactClientContext} for the possible values and their meaning
-   *
-   * @returns {LDReactClientContext} The react context for the LaunchDarkly client.
+   * @see {@link LDReactClientContext}
    */
   reactContext?: LDReactClientContext;
 
diff --git a/packages/sdk/react/src/client/LDReactClient.tsx b/packages/sdk/react/src/client/LDReactClient.tsx
@@ -29,7 +29,7 @@ import { LDReactClientOptions } from './LDOptions';
  *
  * @example
  * ```tsx
- * import { createClient } from '@launchdarkly/react';
+ * import { createClient } from '@launchdarkly/react-sdk';
  * const client = createClient(clientSideID, context, options);
  *
  * await client.start();
diff --git a/packages/sdk/react/src/client/hooks/useVariationCore.ts b/packages/sdk/react/src/client/hooks/useVariationCore.ts
@@ -17,8 +17,9 @@ export default function useVariationCore<T, R = T>(
   // effect hook. These are purposely not dependencies of the effect hook as
   // they should not trigger any changes to the hook state.
   const defaultValueRef = useRef(defaultValue);
-  defaultValueRef.current = defaultValue;
   const evaluateRef = useRef(evaluate);
+
+  defaultValueRef.current = defaultValue;
   evaluateRef.current = evaluate;
 
   const didMountRef = useRef(false);
diff --git a/packages/sdk/react/src/client/provider/LDReactContext.tsx b/packages/sdk/react/src/client/provider/LDReactContext.tsx
@@ -4,15 +4,34 @@ import { createContext } from 'react';
 
 import type { LDReactClientContext, LDReactClientContextValue } from '../LDClient';
 
-// initializes a new context for the LaunchDarkly client. The sole usage of this function
-// is to create a new context so that it could be referenced and managed by the
-// application. This is a common pattern in React to create a new context for a
-// specific purpose.
+/**
+ * Creates a new LaunchDarkly React context.
+ *
+ * @remarks
+ * This function can be used to create different LaunchDarkly contexts for the same
+ * application.
+ *
+ * **NOTE:** This function is not necessary if you are only using a single LaunchDarkly environment.
+ * If that is the case, you can use the {@link LDReactContext} directly.
+ *
+ * @returns A new React context for the LaunchDarkly client.
+ */
 export function initLDReactContext(): LDReactClientContext {
   return createContext<LDReactClientContextValue>(null as any);
 }
 
 /**
- * The LaunchDarkly React context.
+ * The default LaunchDarkly React context.
+ *
+ * @example
+ * ```tsx
+ * import { LDReactContext, useLDClient } from '@launchdarkly/react-sdk';
+ *
+ * function MyComponent() {
+ *   const client = useLDClient(LDReactContext);
+ *   const flagValue = client.boolVariation('my-flag', false);
+ *   return <div>{flagValue ? 'on' : 'off'}</div>;
+ * }
+ * ```
  */
 export const LDReactContext: LDReactClientContext = initLDReactContext();
diff --git a/packages/sdk/react/src/client/provider/LDReactProvider.tsx b/packages/sdk/react/src/client/provider/LDReactProvider.tsx
@@ -11,7 +11,7 @@ import { LDReactContext } from './LDReactContext';
  * Creates a new LaunchDarkly React provider wrapping an existing client instance.
  *
  * @remarks
- * **NOTE:** We recommend using the convenience factory function {@link createLDReactProvider}
+ * **NOTE:** We recommend using the factory function {@link createLDReactProvider}
  * instead of this function if you can.
  *
  * This factory function is provided to allow the caller to use an existing client
diff --git a/packages/sdk/react/src/server/LDIsomorphicProvider.tsx b/packages/sdk/react/src/server/LDIsomorphicProvider.tsx
@@ -40,8 +40,6 @@ export interface LDIsomorphicProviderProps {
  * @remarks
  * **NOTE:** This component is designed to be used in conjunction with {@link LDIsomorphicClientProvider}
  * in a server component to compute the bootstrap data and render this provider automatically.
- *
- * See the `server-only` example for how to use this component.
  */
 export async function LDIsomorphicProvider({
   session,
diff --git a/packages/sdk/react/src/server/LDServerSession.ts b/packages/sdk/react/src/server/LDServerSession.ts
@@ -5,15 +5,11 @@ import { LDContext, type LDFlagsStateOptions } from '@launchdarkly/js-server-sdk
 import { LDServerSession } from './LDClient';
 import { LDServerBaseClient } from './LDServerBaseClient';
 
-// cache() creates a per-request memoized store — each React render tree (request)
+// Creates a per-request memoized store — each React render tree (request)
 // gets its own isolated instance. The store is populated by createLDServerSession
 // and read by useLDServerSession.
 const withCache = cache(() => ({ session: null as LDServerSession | null }));
 
-/**
- * Boundary check for server only code. Given that we are assuming a React ecosystem,
- * simply checking for the presence of window should be sufficient.
- */
 function isServer(): boolean {
   return typeof window === 'undefined';
 }
@@ -35,10 +31,10 @@ function isServer(): boolean {
  * ```ts
  * // lib/ld-server.ts
  * import { init } from '@launchdarkly/node-server-sdk';
- * import { createLDServerSession } from '@launchdarkly/react-sdk/server';
+ * import { createLDServerWrapper } from '@launchdarkly/react-sdk/server';
  *
  * const ldBaseClient = await init(process.env.LAUNCHDARKLY_SDK_KEY || '');
- * export const serverSession = createLDServerSession(ldBaseClient, defaultContext);
+ * export const serverSession = createLDServerWrapper(ldBaseClient, defaultContext);
  * ```
  *
  * @param client Any LaunchDarkly server SDK client that satisfies {@link LDServerBaseClient}.
diff --git a/packages/sdk/react/temp_docs/MIGRATING.md b/packages/sdk/react/temp_docs/MIGRATING.md
@@ -1,30 +1,28 @@
-# Migrating from `launchdarkly-react-client-sdk` v3 to `@launchdarkly/react-sdk`
+# Migrating from `launchdarkly-react-client-sdk` v3 to `@launchdarkly/react-sdk` v4
 
 This document describes the API differences between the legacy `launchdarkly-react-client-sdk` (v3.x)
 and the new `@launchdarkly/react-sdk` package.
 
-With the introduction of server components, we will narrow our official React support to a minimum major version of **18** (peer dependency: `react@>=18.0.0`). Support for React Server Components is experimental and may require React 18 or later.
+With the introduction of server components, we will narrow our official React support to a minimum major version of **18** (peer dependency: `react@>=18.0.0`).
+This SDK supports React server components in `@launchdarkly/react-sdk/server` submodule. It is important to note that React server components are stabilized
+in React 19 and are only stable in a handful of frameworks (as of the time of writing), so you **MUST** be on React 19 to leverage the server submodule.
+Otherwise, being in an earlier version of React **SHOULD** work if you are only using the `@launchdarkly/react-sdk`.
 
+NOTE: the new React SDK will be based on `@launchdarkly/js-client-sdk` which is our JavaScript SDK at version >= 4.0.0. Please also read the differences
+between that version and the older versions of the JavaScript SDK as those changes are also relevant to the React SDK.
+> https://launchdarkly.com/docs/sdk/client-side/javascript/migration-3-to-4
 ---
+## Package name and location
 
-## Hooks
-
-### `useLDClient` — unchanged
-
-```ts
-// Before
-import { useLDClient } from 'launchdarkly-react-client-sdk';
-const client = useLDClient();
-
-// After
-import { useLDClient } from '@launchdarkly/react-sdk';
-const client = useLDClient();
-```
-
-Both return the `LDClient` instance. Use the client directly for `identify()`, `track()`, etc.
+Globally, we've changed our package from `launchdarkly-react-client-sdk` to `@launchdarkly/react-sdk`. The reasoning is:
+1. Scoped packages are easier to manage
+2. We moved the implementation into our `js-core` monorepo which makes downstream dependencies much easier to manage
+3. We took the `client` out of the name as we are also supporting server side rendering with this major version release
 
 ---
 
+## Hooks
+
 ### `useLDClientError` → `useInitializationStatus` (replacement)
 
 The old `useLDClientError()` only returned an error when the client failed to initialize.
@@ -116,6 +114,17 @@ value) without subscribing to every flag change.
 > **Deprecated.** Use individual typed variation hooks (`useBoolVariation`, etc.) or `useLDClient`
 > instead. This hook will be removed in a future major version.
 
+The `useFlags` hook is still available to use, but it is deprecated. We strongly recommend using our typed
+variation hooks for flag evaluations. If you must have a `allFlag` output then you can call `allFlags` directly
+from the LDClient:
+
+```ts
+import { useLDClient } from '@launchdarkly/react-sdk';
+
+const ldClient = useLDClient();
+const flags = ldClient.allFlags();
+```
+
 ---
 
 ## Provider setup
@@ -195,7 +204,7 @@ const LDProvider = await asyncWithLDProvider({ clientSideID: 'your-id', options:
 
 ### New SDK
 
-Bootstrap is a first-class option on `createLDReactProvider`:
+Bootstrap is a top level option on `createLDReactProvider`:
 
 ```tsx
 import { createLDReactProvider } from '@launchdarkly/react-sdk';
@@ -211,7 +220,116 @@ object (`{ 'my-flag': true }`) or the output of `allFlagsState().toJSON()`, whic
 
 ---
 
-## Isomorphic Provider (React Server Components)
+## React server component support
+
+> **New in `@launchdarkly/react-sdk`.**
+
+### `createLDServerSession` (recommended)
+
+Creates a per-request evaluation scope by binding a server SDK client to a specific context.
+The session is cached using React's `cache()` API, so each request gets its own isolated instance.
+This also enables `useLDServerSession()` to retrieve the session from nested Server Components.
+
+```ts
+import { init } from '@launchdarkly/node-server-sdk';
+import { createLDServerSession } from '@launchdarkly/react-sdk/server';
+
+const ldBaseClient = init(process.env.LAUNCHDARKLY_SDK_KEY!);
+
+// In your root Server Component (e.g. app/layout.tsx or app/page.tsx)
+export default async function Page() {
+  await ldBaseClient.waitForInitialization({ timeout: 10 });
+
+  const session = createLDServerSession(ldBaseClient, {
+    kind: 'user',
+    key: 'user-key',
+    name: 'Sandy',
+  });
+
+  const showFeature = await session.boolVariation('show-new-feature', false);
+  return <div>{showFeature ? 'New Feature!' : 'Classic'}</div>;
+}
+```
+
+### `useLDServerSession`
+
+Retrieves the cached session created by `createLDServerSession` from anywhere in the
+Server Component tree. Returns `null` if no session has been created for the current request.
+
+```tsx
+// app/page.tsx — create the session in a parent component
+import { createLDServerSession } from '@launchdarkly/react-sdk/server';
+
+export default async function Page() {
+  await ldBaseClient.waitForInitialization({ timeout: 10 });
+  createLDServerSession(ldBaseClient, { kind: 'user', key: 'user-key' });
+
+  return <FeatureBanner />;
+}
+
+// components/FeatureBanner.tsx — retrieve it in a nested Server Component
+import { useLDServerSession } from '@launchdarkly/react-sdk/server';
+
+export default async function FeatureBanner() {
+  const session = useLDServerSession();
+  if (!session) return null;
+
+  const banner = await session.stringVariation('banner-text', 'Welcome');
+  return <h1>{banner}</h1>;
+}
+```
+
+### `createLDServerWrapper` (advanced)
+
+Same as `createLDServerSession` but does **not** cache the session. Use this when you need
+manual lifecycle control or want to avoid the React `cache()` mechanism.
+
+```ts
+import { createLDServerWrapper } from '@launchdarkly/react-sdk/server';
+
+const session = createLDServerWrapper(ldBaseClient, context);
+```
+
+> **Note:** Sessions created with `createLDServerWrapper` are not retrievable via
+> `useLDServerSession()`. You must pass the session through props or module scope yourself.
+
+### Server-only usage (without client hydration)
+
+If your page is entirely server-rendered and you don't need client-side live updates, you can
+use `createLDServerSession` directly without `LDIsomorphicProvider`:
+
+```tsx
+// app/dashboard/page.tsx — pure Server Component, no client SDK needed
+import { init } from '@launchdarkly/node-server-sdk';
+import { createLDServerSession } from '@launchdarkly/react-sdk/server';
+
+const ldBaseClient = init(process.env.LAUNCHDARKLY_SDK_KEY!);
+
+export default async function Dashboard() {
+  await ldBaseClient.waitForInitialization({ timeout: 10 });
+
+  const session = createLDServerSession(ldBaseClient, {
+    kind: 'user',
+    key: 'user-key',
+  });
+
+  const maxItems = await session.numberVariation('max-dashboard-items', 5);
+  const theme = await session.stringVariation('ui-theme', 'light');
+
+  return (
+    <div className={theme}>
+      <ItemList limit={maxItems} />
+    </div>
+  );
+}
+```
+
+This is simpler than the isomorphic approach but flags will not update until the next
+server render (e.g. page navigation or revalidation).
+
+---
+
+## Isomorphic Provider
 
 > **New in `@launchdarkly/react-sdk`.**
 
@@ -263,18 +381,6 @@ Server Components inside the provider tree can call `session.boolVariation(...)`
 Client Components use the standard hooks (`useBoolVariation`, etc.) — they read from the
 bootstrapped data on first render and receive live updates afterwards.
 
-## Removed APIs
-
-| Old API | Status | Replacement |
-|---------|--------|-------------|
-| `useLDClientError()` | Removed | `useInitializationStatus().error` |
-| `useFlag()` | Removed | `useBoolVariation`, `useStringVariation`, `useNumberVariation`, `useJsonVariation` |
-| `useFlagDetail()` | Removed | `useBoolVariationDetail`, `useStringVariationDetail`, `useNumberVariationDetail`, `useJsonVariationDetail` |
-| `withLDProvider()` | Removed | `createLDReactProvider()` |
-| `asyncWithLDProvider()` | Removed | `createLDReactProvider()` |
-| `withLDConsumer()` | Removed | `useLDClient()`, typed variation hooks (`useBoolVariation`, etc.) |
-| `LDProvider` component | Removed | `createLDReactProvider()` |
-
 ---
 
 ## Multiple environments
@@ -366,3 +472,16 @@ function MyComponent() {
   return <div>{myFlag ? 'on' : 'off'}</div>;
 }
 ```
+---
+
+## Removed APIs
+
+| Old API | Status | Replacement |
+|---------|--------|-------------|
+| `useLDClientError()` | Removed | `useInitializationStatus().error` |
+| `useFlag()` | Removed | `useBoolVariation`, `useStringVariation`, `useNumberVariation`, `useJsonVariation` |
+| `useFlagDetail()` | Removed | `useBoolVariationDetail`, `useStringVariationDetail`, `useNumberVariationDetail`, `useJsonVariationDetail` |
+| `withLDProvider()` | Removed | `createLDReactProvider()` |
+| `asyncWithLDProvider()` | Removed | `createLDReactProvider()` |
+| `withLDConsumer()` | Removed | `useLDClient()`, typed variation hooks (`useBoolVariation`, etc.) |
+| `LDProvider` component | Removed | `createLDReactProvider()` |

Original file line number	Diff line number	Diff line change
`@@ -59,7 +59,7 @@ export interface LDReactClient extends LDClient {`
`59`	`59`	`/**`
`60`	`60`	`* Returns whether the client is ready to evaluate flags. This is true when the client`
`61`	`61`	`* has completed initialization (successfully or with failure), or when bootstrap data`
`62`		- * was provided (flags are available immediately via `presetFlags`).
	`62`	`+ * was provided.`
`63`	`63`	`*`
`64`	`64`	`* @returns {boolean} Whether the client can evaluate flags.`
`65`	`65`	`*/`
`@@ -68,8 +68,8 @@ export interface LDReactClient extends LDClient {`
`68`	`68`	`/**`
`69`	`69`	`* @internal`
`70`	`70`	`*`
`71`		- * Returns whether flag keys should be converted to camelCase in `useFlags()` and resolved from camelCase
`72`		- * in the individual variation hooks. Defaults to `true` when absent.
	`71`	+ * Returns whether flag keys should be converted to camelCase in `useFlags()`.
	`72`	+ * Defaults to `true` when absent.
`73`	`73`	`*`
`74`	`74`	`* @remarks`
`75`	`75`	* NOTE: This method is only used by `useFlags()` hook.
Original file line number	Diff line number	Diff line change
`@@ -29,7 +29,7 @@ import { LDReactClientOptions } from './LDOptions';`
`29`	`29`	`*`
`30`	`30`	`* @example`
`31`	`31`	* ```tsx
`32`		`- * import { createClient } from '@launchdarkly/react';`
	`32`	`+ * import { createClient } from '@launchdarkly/react-sdk';`
`33`	`33`	`* const client = createClient(clientSideID, context, options);`
`34`	`34`	`*`
`35`	`35`	`* await client.start();`
Original file line number	Diff line number	Diff line change
`@@ -11,7 +11,7 @@ import { LDReactContext } from './LDReactContext';`
`11`	`11`	`* Creates a new LaunchDarkly React provider wrapping an existing client instance.`
`12`	`12`	`*`
`13`	`13`	`* @remarks`
`14`		`- * NOTE: We recommend using the convenience factory function {@link createLDReactProvider}`
	`14`	`+ * NOTE: We recommend using the factory function {@link createLDReactProvider}`
`15`	`15`	`* instead of this function if you can.`
`16`	`16`	`*`
`17`	`17`	`* This factory function is provided to allow the caller to use an existing client`