chore: create React SDK scaffold

package.json

@@ -16,6 +16,8 @@
     "packages/sdk/electron",
     "packages/sdk/fastly",
     "packages/sdk/fastly/example",
+    "packages/sdk/react",
+    "packages/sdk/react/contract-tests",
     "packages/sdk/react-native",
     "packages/sdk/react-native/example",
     "packages/sdk/react-universal",

packages/sdk/react/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 Catamorphic, Co.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

packages/sdk/react/README.md

@@ -0,0 +1,21 @@
+# LaunchDarkly React SDK
+
+> [!CAUTION]
+> This [SDK|feature] is experimental and should NOT be considered ready for production use. 
+> It may change or be removed without notice and is not subject to backwards 
+> compatibility guarantees.
+
+## 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:
+  - Roll out a new feature to a subset of your users (like a group of users who opt-in to a beta tester group), gathering feedback and bug reports from real-world use cases.
+  - Gradually roll out a feature to an increasing percentage of users, and track the effect that the feature has on key metrics (for instance, how likely is a user to complete a purchase if they have feature A versus feature B?).
+  - Turn off a feature that you realize is causing performance problems in production, without needing to re-deploy, or even restart the application with a changed configuration file.
+  - Grant access to certain features based on user attributes, like payment plan (eg: users on the ‘gold’ plan get access to more features than users in the ‘silver’ plan).
+  - Disable parts of your application to facilitate maintenance, without taking everything offline.
+- LaunchDarkly provides feature flag SDKs for a wide variety of languages and technologies. Read [our documentation](https://docs.launchdarkly.com/sdk) for a complete list.
+- Explore LaunchDarkly
+  - [launchdarkly.com](https://www.launchdarkly.com/ 'LaunchDarkly Main Website') for more information
+  - [docs.launchdarkly.com](https://docs.launchdarkly.com/ 'LaunchDarkly Documentation') for our documentation and SDK reference guides
+  - [apidocs.launchdarkly.com](https://apidocs.launchdarkly.com/ 'LaunchDarkly API Documentation') for our API documentation
+  - [blog.launchdarkly.com](https://blog.launchdarkly.com/ 'LaunchDarkly Blog Documentation') for the latest product updates

packages/sdk/react/__tests__/index.test.ts

@@ -0,0 +1,3 @@
+describe('react-sdk', () => {
+  test.todo('Add react sdk tests');
+});

packages/sdk/react/contract-tests/README.md

@@ -0,0 +1,2 @@
+# React SDK contract-tests
+

packages/sdk/react/contract-tests/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "@internal/react-sdk-contract-tests",
+  "packageManager": "yarn@3.4.1"
+}

packages/sdk/react/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@launchdarkly/react-sdk",
+  "version": "0.0.1",
+  "description": "LaunchDarkly SDK for React frameworks",
+  "homepage": "https://github.com/launchdarkly/js-core/tree/main/packages/sdk/react",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/launchdarkly/js-core.git"
+  },
+  "license": "Apache-2.0",
+  "packageManager": "yarn@4.2.2",
+  "keywords": [
+    "launchdarkly",
+    "react",
+    "isomorphic",
+    "nextjs",
+    "remix"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./client": {
+      "types": "./dist/src/client/index.d.ts",
+      "default": "./dist/src/client/index.js"
+    },
+    "./server": {
+      "types": "./dist/src/server/index.d.ts",
+      "default": "./dist/src/server/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "typedoc": "0.25.0",
+    "typescript": "5.1.6"
+  },
+  "dependencies": {
+    "@launchdarkly/js-client-sdk": "workspace:^",
+    "@launchdarkly/js-client-sdk-common": "workspace:^",
+    "@launchdarkly/js-server-sdk-common": "workspace:^"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  }
+}

packages/sdk/react/src/LDIsomorphicClient.ts

@@ -0,0 +1,30 @@
+import { LDReactClient } from './client/LDClient';
+import { LDReactServerClient } from './server/LDClient';
+
+/**
+ * The LaunchDarkly isomorphic client interface.
+ *
+ * This is a common interface that can be used to create a client
+ * that can be used on the server and client sides.
+ *
+ * @privateRemarks
+ * NOTE: This interface might be replaced shared functions in the future which
+ * maybe better for tree shaking.
+ */
+export interface LDIsomorphicClient extends Omit<
+  LDReactClient,
+  'waitForInitialization' | 'start' | 'addHook'
+> {
+
+  /**
+   * A builder function that will federate the current client with a server component.
+   * RSC components will ONLY be available if this function is called.
+   *
+   * @remarks
+   * By default, the react client will only be doing client side rendering.
+   *
+   * @param LDServerClient A LaunchDarkly server client
+   * @returns 
+   */
+  useServerClient: (LDServerClient: LDReactServerClient) => this;
+}

packages/sdk/react/src/LDIsomorphicOptions.ts

@@ -0,0 +1,7 @@
+import { LDReactClientOptions } from "./client/LDOptions";
+
+/**
+ * Options for creating an isomorphic client.
+ */
+export interface LDIsomorphicOptions extends LDReactClientOptions {
+}

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

@@ -0,0 +1,58 @@
+import { LDClient, LDContext, LDWaitForInitializationResult } from '@launchdarkly/js-client-sdk';
+
+/**
+ * Initialization state of the client. This type should be consistent with 
+ * the `status` field of the `LDWaitForInitializationResult` type.
+ */
+export type IntializedState = LDWaitForInitializationResult['status'] | 'initializing' | 'unknown';
+
+/**
+ * The LaunchDarkly client interface for React.
+ *
+ * @privateRemarks
+ * We will provide 2 ways to create instances of LDClient:
+ * 1. A `createClient` function that is similar to the js-client-sdk's `createClient` function.
+ * 2. A `createLDProvider` function that creates a React Context
+ *
+ */
+export interface LDReactClient extends LDClient {
+  /**
+   * Returns the initialization state of the client. This function is helpful to determine
+   * whether LDClient can be used to evaluate flags on intial component render.
+   *
+   * @see {@link LDWaitForInitializationResult} for the possible values and their meaning
+   *
+   * @returns {IntializedState} The initialization state of the client.
+   */
+  getInitializationState(): IntializedState;
+}
+
+/**
+ * The react context interface for the launchdarkly client. This will be the type that is
+ * used in the `createContext` function.
+ */
+export interface LDReactClientContextValue {
+  /**
+   * The LaunchDarkly client.
+   */
+  client: LDReactClient;
+
+  /**
+   * The LaunchDarkly context.
+   */
+  context: LDContext;
+
+  /**
+   * The initialization state of the client.
+   */
+  intializedState: IntializedState;
+}
+
+/**
+ * The LaunchDarkly client context provider interface for React.
+ * This will be the type that is returned from our createContext function.
+ */
+export interface LDReactClientContextProvider {
+  Context: React.Context<LDReactClientContextValue>;
+}
+

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

@@ -0,0 +1,67 @@
+import { LDContext, LDOptions as LDOptionsBase, LDStartOptions } from '@launchdarkly/js-client-sdk';
+
+/**
+ * Initialization options for the LaunchDarkly React SDK.
+ */
+export interface LDReactClientOptions extends LDOptionsBase {
+  /**
+   * Whether the React SDK should transform flag keys into camel-cased format.
+   * Using camel-cased flag keys allow for easier use as prop values, however,
+   * these keys won't directly match the flag keys as known to LaunchDarkly.
+   * Consequently, flag key collisions may be possible and the Code References feature
+   * will not function properly.
+   *
+   * This is true by default, meaning that keys will automatically be converted to camel-case.
+   *
+   * For more information, see the React SDK Reference Guide on
+   * [flag keys](https://docs.launchdarkly.com/sdk/client-side/react/react-web#flag-keys).
+   *
+   * @see https://docs.launchdarkly.com/sdk/client-side/react/react-web#flag-keys
+   */
+  useCamelCaseFlagKeys?: boolean;
+}
+
+/**
+ * Options for creating a React Provider.
+ */
+export interface LDReactProviderOptions {
+  /**
+   * LaunchDarkly initialization options. These options are common between LaunchDarkly's JavaScript and React SDKs.
+   *
+   * @see {@link LDReactClientOptions} for the possible options
+   */
+  options?: LDReactClientOptions;
+
+  /**
+   * Your project and environment specific client side ID. You can find
+   * this in your LaunchDarkly portal under Account settings.
+   */
+  clientSideID: string;
+
+  /**
+   * A LaunchDarkly context object. This will be used as the initial
+   * context for the client.
+   */
+  context: LDContext;
+
+  /**
+   * Options for starting the LaunchDarkly client.
+   *
+   * @remarks
+   * This option is especially useful if you choose to not defer
+   * initialization and want to start the client immediately.
+   *
+   * @see {@link LDStartOptions} for the possible options
+   */
+  startOptions?: LDStartOptions;
+
+  /**
+   * If set to false, the LDClient will initialize immediately.
+   *
+   * @default true
+   *
+   * If intiailization is deferred, then the LDClient can be initialized manually
+   * by calling the `start` function.
+   */
+  deferInitialization?: boolean;
+}

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

@@ -0,0 +1,108 @@
+import { LDReactClient, LDReactClientContextProvider, LDReactClientContextValue } from './LDClient';
+import { createContext as createReactContext } from 'react';
+import { LDReactClientOptions } from './LDOptions';
+import { LDContext } from '@launchdarkly/js-client-sdk';
+
+export type * from '@launchdarkly/js-client-sdk';
+export * from './LDClient';
+export * from './LDOptions';
+
+/** 
+ * Creates a new instance of the LaunchDarkly client.
+ * 
+ * @remarks
+ * 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.
+ * 
+ * we DO NOT recommend using this client creation method.
+ *
+ * @example
+ * ```tsx
+ * import { createClient } from '@launchdarkly/react';
+ * const client = createClient(clientSideID, context, options);
+ * ```
+ * 
+ * @param clientSideID 
+ * @param context 
+ * @param options 
+ * @returns 
+ */
+// ts-expect-error - TODO: implement this
+export function createClient(clientSideID: string, context: LDContext, options?: LDReactClientOptions): LDReactClient {
+  // TODO: implement this
+  return null as any;
+}
+
+/**
+ * Creates a new context provider from a LaunchDarkly client instance.
+ * 
+ * @remarks
+ * We export this function so that developers can more easily manage their own client instance.
+ * This was how we supported multiple client instances in the past.
+ * 
+ * we DO NOT recommend using this client creation method.
+ *
+ * @param client A LaunchDarkly client instance.
+ * @returns A LaunchDarkly client context provider.
+ */
+// ts-expect-error - TODO: implement this
+export function createContextFromClient(client: LDReactClient): LDReactClientContextProvider {
+  // TODO: implement this
+  return null as any;
+}
+
+/**
+ * Creates a new context provider for the LaunchDarkly client.
+ * 
+ * TODO: this is unfinished and is only here to provide some reminders
+ * of what I was thinking.
+ * 
+ * @example
+ * 
+ * ```tsx
+ * const { Context, useContext } = createContext();
+ *
+ * function MyComponent() {
+ *   const { client, context, intializedState } = useContext();
+ *   return <div>Client: {client.toString()}, Context: {context.toString()}, InitializedState: {intializedState}</div>;
+ * }
+ * ```
+ * 
+ * Typically, in React applications, you might want to export the context so that it can be used in other
+ * components.
+ * 
+ * ```tsx
+ * export createContext();
+ * ```
+ * 
+ * ```tsx
+ * import { Context } from './path/to/context';
+ *
+ * function MyComponent() {
+ *   const { client, context, intializedState } = useContext(Context);
+ *   return <div>Client: {client.toString()}, Context: {context.toString()}, InitializedState: {intializedState}</div>;
+ * }
+ *
+ * function MyOtherComponent() {
+ *   return <Context value={{ client, context, intializedState }}>
+ *     <MyComponent />
+ *   </Context>;
+ * }
+ * ```
+ * 
+ * @returns The LaunchDarkly client context provider.
+ */
+export function createClientContext(clientSideID: string, context: LDContext, options?: LDReactClientOptions): LDReactClientContextProvider {
+  const client = createClient(clientSideID, context, options);
+  const Context = createReactContext<LDReactClientContextValue>({
+    client,
+    context,
+    intializedState: 'unknown',
+  });
+
+  return {
+    Context,
+  };
+}
+

packages/sdk/react/src/index.ts

@@ -0,0 +1,11 @@
+import { LDIsomorphicClient } from "./LDIsomorphicClient";
+import { LDContext } from "@launchdarkly/js-client-sdk";
+import { LDIsomorphicOptions } from "./LDIsomorphicOptions";
+
+/**
+ * Creates a new instance of the launchdarkly client.
+ */
+// @ts-expect-error - TODO: implement this
+export function createClient(clientSideID: string, context: LDContext, options?: LDIsomorphicOptions): LDIsomorphicClient {
+
+}