docs: updating docs to clarify usage (#1205)

<!-- CURSOR_SUMMARY -->
> [!NOTE]
> **Low Risk**
> Mostly documentation/comment and export-surface adjustments; minimal
runtime impact aside from removing the `isServer` test/export and
tightening what `LDReactContext` exports.
> 
> **Overview**
> Clarifies public API guidance across the React SDK (client creation,
provider usage, initialization status, and server session patterns) via
updated JSDoc and expanded `MIGRATING.md`, including stating a React 18+
support baseline and documenting `useFlag`/`useFlagDetail` as removed.
> 
> Cleans up the export surface by switching `client/index.ts` to
explicitly export `LDReactContext`/`initLDReactContext`, making
`isServer()` internal-only (and removing its unit test), and deleting
the temporary docs directory content.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
3d0039a. 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/1205"
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__/server/createLDServerSession.test.ts

@@ -1,6 +1,6 @@
 import { LDContext, LDFlagsStateOptions } from '@launchdarkly/js-server-sdk-common';
 
-import { createLDServerSession, isServer } from '../../src/server/index';
+import { createLDServerSession } from '../../src/server/index';
 
 const context: LDContext = { kind: 'user', key: 'test-user' };
 
@@ -36,10 +36,6 @@ function makeMockBaseClient() {
   };
 }
 
-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);

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

@@ -42,9 +42,7 @@ export interface LDReactClient extends LDClient {
   onContextChange(callback: (context: LDContextStrict) => void): () => void;
 
   /**
-   * Subscribes to initialization status changes triggered by `start()`. The callback is
-   * invoked once `start()` resolves. If `start()` has already resolved when this is called,
-   * the callback is invoked immediately with the last result.
+   * Subscribes to initialization status changes triggered when the client is initialized.
    *
    * @param callback Function called with the initialization result.
    * @returns An unsubscribe function. Call it to stop receiving notifications.
@@ -54,9 +52,14 @@ export interface LDReactClient extends LDClient {
   ): () => void;
 
   /**
+   * @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.
    *
+   * @remarks
+   * **NOTE:** This method is only used by `useFlags()` hook.
+   *
    * @deprecated This method is deprecated and will be removed in a future major version.
    *
    * @returns {boolean} Whether flag keys should be converted to camelCase.
@@ -65,8 +68,7 @@ export interface LDReactClient extends LDClient {
 }
 
 /**
- * The react context interface for the launchdarkly client. This will be the type that is
- * used in the `createContext` function.
+ * The React context interface for the LaunchDarkly client.
  */
 export interface LDReactClientContextValue {
   /**

packages/sdk/react/src/client/LDReactClient.tsx

@@ -21,16 +21,8 @@ function noopDetail<T>(defaultValue: T): { value: T; kind: LDEvaluationReason['k
 }
 
 /**
- * Returns a noop LDReactClient for use on the server. Never instantiates the browser SDK.
- * This is useful when dealing with applications that are using React Server Components.
- *
- * This fallback is helpful when compilers attempt to prerender components on build time.
- * This will enable the components to at least be prerendered with their default values.
- *
- * @privateRemarks TODO
- * I think we should move this and the server noop to a shared location... currently we
- * are separating everything to trivialize network boundary and tree shaking concerns.
- * But we shouldn't have any problems having some shared modules.
+ * @privateRemarks
+ * **WARNING:** This function is going to be removed soon! sdk-2043
  */
 function createNoopReactClient(): LDReactClient {
   return {
@@ -89,23 +81,28 @@ function createNoopReactClient(): LDReactClient {
  * Creates a new instance of the LaunchDarkly client for React.
  *
  * @remarks
- * When called on the server, returns a noop client that never instantiates the browser SDK.
- * This function is exported so that developers can have more flexibility in client creation.
- * More so this is to preserve previous behavior of app developers managing their own client
- * instance.
+ * **NOTE:** We recommend using the convenience factory function {@link createLDReactProvider}
+ * instead of this function to create your client instance if you can.
  *
- * we DO NOT recommend using this client creation method.
+ * This factory function is provided to allow the caller to have more control over their client instance.
+ * When using this function, the caller is responsible for:
+ *  - calling `client.start()` before or after mounting.
+ *  - subscribing to client lifecycle events.
+ *
+ * Refer to {@link createLDReactProviderWithClient} for the default behavior.
  *
  * @example
  * ```tsx
  * import { createClient } from '@launchdarkly/react';
  * const client = createClient(clientSideID, context, options);
+ *
+ * await client.start();
  * ```
  *
  * @param clientSideID launchdarkly client side id @see https://launchdarkly.com/docs/sdk/concepts/client-side-server-side#client-side-id
  * @param context launchdarkly context @see https://launchdarkly.com/docs/sdk/concepts/context
- * @param options
- * @returns
+ * @param options options for the client @see {@link LDReactClientOptions}
+ * @returns the new client instance @see {@link LDReactClient}
  */
 export function createClient(
   clientSideID: string,

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

@@ -1,7 +1,6 @@
 /**
  * Converts a flag key to camelCase, matching the behavior of the legacy
- * launchdarkly-react-client-sdk. Handles kebab-case, snake_case, dot.separated,
- * ALL_CAPS, and already-camelCased keys.
+ * launchdarkly-react-client-sdk.
  *
  * Examples:
  *   'my-flag-key'  → 'myFlagKey'
@@ -13,8 +12,8 @@
  */
 export function toCamelCase(key: string): string {
   return key
-    .replace(/([a-z\d])([A-Z])/g, '$1 $2') // camelCase boundary: myFlag → my Flag, my2Flag → my2 Flag
-    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2') // ALLCAPS boundary: HTMLParser → HTML Parser
+    .replace(/([a-z\d])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
     .split(/[-._\s]+/)
     .filter(Boolean)
     .map((word, i) => {

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

@@ -21,10 +21,10 @@ function toFlagsProxy<T extends LDFlagSet>(client: LDReactClient, rawFlags: T):
   // Pre-build the display object, filtering out $ system keys.
   // Mirrors getCamelizedKeysAndFlagMap in the old react-client-sdk.
   const displayFlags: LDFlagSet = {};
-  const flagKeyMap: Record<string, string> = {}; // camelKey -> originalKey
+  const flagKeyMap: Record<string, string> = {};
 
   Object.keys(rawFlags as LDFlagSet)
-    .filter((rawKey) => rawKey.indexOf('$') !== 0) // exclude system keys (matches old SDK)
+    .filter((rawKey) => rawKey.indexOf('$') !== 0)
     .forEach((rawKey) => {
       if (useCamelCase) {
         const camelKey = toCamelCase(rawKey);
@@ -35,13 +35,10 @@ function toFlagsProxy<T extends LDFlagSet>(client: LDReactClient, rawFlags: T):
       }
     });
 
-  // Only a get trap — matches old SDK's toFlagsProxy scope.
   return new Proxy(displayFlags as T, {
     get(target, prop, receiver) {
       const currentValue = Reflect.get(target, prop, receiver);
 
-      // Only intercept own flag keys; pass through symbols and prototype methods.
-      // Equivalent to old SDK: hasFlag(flagKeyMap, prop) || hasFlag(target, prop)
       if (typeof prop === 'symbol' || !Object.prototype.hasOwnProperty.call(target, prop)) {
         return currentValue;
       }
@@ -65,15 +62,7 @@ function toFlagsProxy<T extends LDFlagSet>(client: LDReactClient, rawFlags: T):
 }
 
 /**
- * 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.
- *
- * @remarks
- * When `useCamelCaseFlagKeys` is `true`, flag keys are converted to camelCase.
- * This means `"my-flag"` is accessible as `flags.myFlag`. Note that key collisions may occur
- * if two flag keys differ only in separators (e.g. `'my-flag'` and `'my.flag'` both map to
- * `'myFlag'` — last key wins), and Code References will not function correctly with camelCased keys.
+ * Returns all feature flags for the current context.
  *
  * @param reactContext Optional React context to read from. Defaults to the global `LDReactContext`.
  * @returns All current flag values, optionally with camelCased keys, wrapped in a proxy that

packages/sdk/react/src/client/hooks/useInitializationStatus.ts

@@ -6,15 +6,7 @@ import type { LDReactClientContextValue } from '../LDClient';
 import { LDReactContext } from '../provider/LDReactContext';
 
 /**
- * The result of `useInitializationStatus`. Represents the current initialization
- * state of the LaunchDarkly client.
- *
- * @remarks
- * This replaces `useLDClientError` from `launchdarkly-react-client-sdk`. It provides
- * richer information: both the initialization state and the error (if any).
- *
- * Use `useInitializationStatus().error` to access the error,
- * and `useInitializationStatus().status` to determine the full state.
+ * Represents the current initialization state of the LaunchDarkly client.
  */
 export type InitializationStatus =
   | { status: 'unknown' }

packages/sdk/react/src/client/hooks/useVariation.ts

@@ -4,7 +4,7 @@ import type { LDReactClientContextValue } from '../LDClient';
 import useVariationCore from './useVariationCore';
 
 /**
- * Returns the boolean variation of a feature flag, re-rendering only when that specific flag changes.
+ * Returns the boolean variation of a feature flag.
  *
  * @param key The feature flag key.
  * @param defaultValue The value to return if the flag is not available.
@@ -25,7 +25,7 @@ export function useBoolVariation(
 }
 
 /**
- * Returns the string variation of a feature flag, re-rendering only when that specific flag changes.
+ * Returns the string variation of a feature flag.
  *
  * @param key The feature flag key.
  * @param defaultValue The value to return if the flag is not available.
@@ -46,7 +46,7 @@ export function useStringVariation(
 }
 
 /**
- * Returns the numeric variation of a feature flag, re-rendering only when that specific flag changes.
+ * Returns the numeric variation of a feature flag.
  *
  * @param key The feature flag key.
  * @param defaultValue The value to return if the flag is not available.
@@ -67,7 +67,7 @@ export function useNumberVariation(
 }
 
 /**
- * Returns the JSON variation of a feature flag, re-rendering only when that specific flag changes.
+ * Returns the JSON variation of a feature flag.
  *
  * @param key The feature flag key.
  * @param defaultValue The value to return if the flag is not available.

packages/sdk/react/src/client/hooks/useVariationDetail.ts

@@ -6,8 +6,7 @@ import type { LDReactClientContextValue } from '../LDClient';
 import useVariationCore from './useVariationCore';
 
 /**
- * Returns the boolean variation and evaluation detail of a feature flag, re-rendering only when
- * that specific flag changes.
+ * Returns the boolean variation and evaluation detail of a feature flag.
  *
  * @param key The feature flag key.
  * @param defaultValue The value to return if the flag is not available.
@@ -28,8 +27,7 @@ export function useBoolVariationDetail(
 }
 
 /**
- * Returns the string variation and evaluation detail of a feature flag, re-rendering only when
- * that specific flag changes.
+ * Returns the string variation and evaluation detail of a feature flag.
  *
  * @param key The feature flag key.
  * @param defaultValue The value to return if the flag is not available.
@@ -50,8 +48,7 @@ export function useStringVariationDetail(
 }
 
 /**
- * Returns the numeric variation and evaluation detail of a feature flag, re-rendering only when
- * that specific flag changes.
+ * Returns the numeric variation and evaluation detail of a feature flag.
  *
  * @param key The feature flag key.
  * @param defaultValue The value to return if the flag is not available.
@@ -72,8 +69,7 @@ export function useNumberVariationDetail(
 }
 
 /**
- * Returns the JSON variation and evaluation detail of a feature flag, re-rendering only when
- * that specific flag changes.
+ * Returns the JSON variation and evaluation detail of a feature flag.
  *
  * @param key The feature flag key.
  * @param defaultValue The value to return if the flag is not available.

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

@@ -2,7 +2,7 @@ export type * from '@launchdarkly/js-client-sdk';
 export * from './LDClient';
 export * from './LDOptions';
 
-export * from './provider/LDReactContext';
+export { LDReactContext, initLDReactContext } from './provider/LDReactContext';
 export { createLDReactProvider, createLDReactProviderWithClient } from './provider/LDReactProvider';
 export { createClient } from './LDReactClient';
 

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

@@ -12,4 +12,7 @@ export function initLDReactContext(): LDReactClientContext {
   return createContext<LDReactClientContextValue>(null as any);
 }
 
+/**
+ * The LaunchDarkly React context.
+ */
 export const LDReactContext: LDReactClientContext = initLDReactContext();