feat: add react sdk

Author: tilyupo

eslint.config.mjs

@@ -1,5 +1,7 @@
 import eslint from "@eslint/js";
 import tseslint from "typescript-eslint";
+import reactPlugin from "eslint-plugin-react";
+import reactHooksPlugin from "eslint-plugin-react-hooks";
 
 export default tseslint.config(
   eslint.configs.recommended,
@@ -17,7 +19,33 @@ export default tseslint.config(
       "no-console": "off",
     },
   },
+  // React-specific config for packages/react and packages/next
   {
-    ignores: ["dist/**", "node_modules/**", "*.config.*"],
+    files: ["packages/react/**/*.{ts,tsx}", "packages/next/**/*.{ts,tsx}"],
+    plugins: {
+      react: reactPlugin,
+      "react-hooks": reactHooksPlugin,
+    },
+    languageOptions: {
+      parserOptions: {
+        ecmaFeatures: {
+          jsx: true,
+        },
+      },
+    },
+    settings: {
+      react: {
+        version: "detect",
+      },
+    },
+    rules: {
+      ...reactPlugin.configs.recommended.rules,
+      ...reactPlugin.configs["jsx-runtime"].rules,
+      ...reactHooksPlugin.configs.recommended.rules,
+      "react/prop-types": "off",
+    },
+  },
+  {
+    ignores: ["**/dist/**", "**/node_modules/**", "**/*.config.*"],
   }
 );

package.json

@@ -1,71 +1,29 @@
 {
-  "name": "@replanejs/sdk",
-  "version": "0.6.1",
-  "description": "Dynamic configuration SDK for browser and server environments (Node.js, Deno, Bun). Powered by Replane.",
-  "type": "module",
-  "license": "MIT",
-  "homepage": "https://github.com/replane-dev/replane-javascript#readme",
-  "bugs": {
-    "url": "https://github.com/replane-dev/replane-javascript/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/replane-dev/replane-javascript.git"
-  },
-  "author": "Dmitry Tilyupo <tilyupo@gmail.com>",
-  "files": [
-    "dist"
-  ],
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    },
-    "./package.json": "./package.json"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "replane",
-    "config",
-    "configuration",
-    "dynamic configuration",
-    "remote config",
-    "feature-flags"
-  ],
-  "sideEffects": false,
+  "name": "replanejs",
+  "private": true,
+  "description": "Replane JavaScript SDKs monorepo",
   "scripts": {
-    "build": "pnpm run build:esm && pnpm run build:cjs",
-    "build:esm": "tsdown",
-    "build:cjs": "esbuild src/index.ts --platform=node --format=cjs --outfile=dist/index.cjs",
-    "dev": "tsdown --watch",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src tests --max-warnings 0",
-    "lint:fix": "eslint src tests --fix",
-    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\" \"README.md\"",
-    "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\" \"README.md\"",
-    "release": "pnpm run build && bumpp && npm publish"
+    "build": "pnpm -r build",
+    "test": "pnpm -r test",
+    "typecheck": "pnpm -r typecheck",
+    "lint": "eslint packages --max-warnings 0",
+    "lint:fix": "eslint packages --fix",
+    "format": "prettier --write \"packages/**/*.{ts,tsx}\"",
+    "format:check": "prettier --check \"packages/**/*.{ts,tsx}\"",
+    "clean": "pnpm -r exec rm -rf dist node_modules"
   },
   "devDependencies": {
     "@eslint/js": "^9.18.0",
-    "@types/node": "^22.15.17",
-    "@typescript-eslint/eslint-plugin": "^8.20.0",
-    "@typescript-eslint/parser": "^8.20.0",
-    "async-channel": "^0.2.0",
-    "bumpp": "^10.1.0",
-    "esbuild": "^0.23.1",
+    "@types/node": "^25.0.3",
     "eslint": "^9.18.0",
-    "prettier": "^3.4.2",
-    "tsdown": "^0.11.9",
-    "typescript": "^5.8.3",
-    "typescript-eslint": "^8.20.0",
-    "vitest": "^3.1.3"
+    "eslint-plugin-react": "^7.37.0",
+    "eslint-plugin-react-hooks": "^5.0.0",
+    "prettier": "^3.4.0",
+    "typescript": "^5.4.0",
+    "typescript-eslint": "^8.20.0"
   },
-  "packageManager": "pnpm@10.7.0+sha1.66453f13fbf9078d3db193718206a8d738afdbdb"
+  "packageManager": "pnpm@10.25.0",
+  "engines": {
+    "node": ">=18.0.0"
+  }
 }

packages/react/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@replanejs/react",
+  "version": "0.1.0",
+  "description": "React SDK for Replane - feature flags and remote configuration",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "pnpm run build"
+  },
+  "keywords": [
+    "replane",
+    "react",
+    "feature-flags",
+    "remote-config",
+    "configuration",
+    "sdk"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/replane-dev/replane-javascript",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/replane-dev/replane-javascript/issues"
+  },
+  "homepage": "https://github.com/replane-dev/replane-javascript#readme",
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "dependencies": {
+    "@replanejs/sdk": "workspace:*"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.1",
+    "@types/node": "^22.19.3",
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.3.7",
+    "jsdom": "^27.3.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.3.1",
+    "tsdown": "^0.11.9",
+    "typescript": "^5.4.0",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/react/src/context.ts

@@ -0,0 +1,5 @@
+import { createContext } from "react";
+import type { ReplaneContextValue } from "./types";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const ReplaneContext = createContext<ReplaneContextValue<any> | null>(null);

packages/react/src/hooks.ts

@@ -0,0 +1,29 @@
+import { useContext, useSyncExternalStore } from "react";
+import { ReplaneContext } from "./context";
+import type { ReplaneContextValue } from "./types";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function useReplane<T extends object = any>(): ReplaneContextValue<T> {
+  const context = useContext(ReplaneContext);
+  if (!context) {
+    throw new Error("useReplane must be used within a ReplaneProvider");
+  }
+  return context as ReplaneContextValue<T>;
+}
+
+export function useConfig<T>(
+  name: string,
+  options?: { context?: Record<string, string | number | boolean | null> }
+): T {
+  const { client } = useReplane();
+
+  const value = useSyncExternalStore(
+    (onStoreChange) => {
+      return client.subscribe(name, onStoreChange);
+    },
+    () => client.get(name, options) as T,
+    () => client.get(name, options) as T
+  );
+
+  return value;
+}

packages/react/src/index.ts

@@ -0,0 +1,9 @@
+export { ReplaneProvider } from "./provider";
+export { useReplane, useConfig } from "./hooks";
+export { clearSuspenseCache } from "./useReplaneClient";
+export type {
+  ReplaneProviderProps,
+  ReplaneProviderWithClientProps,
+  ReplaneProviderWithOptionsProps,
+  ReplaneContextValue,
+} from "./types";

packages/react/src/provider.tsx

@@ -0,0 +1,105 @@
+import { useMemo } from "react";
+import { ReplaneContext } from "./context";
+import { useReplaneClient, useReplaneClientSuspense } from "./useReplaneClient";
+import type {
+  ReplaneProviderProps,
+  ReplaneProviderWithClientProps,
+  ReplaneProviderWithOptionsProps,
+  ReplaneContextValue,
+} from "./types";
+import { hasClient } from "./types";
+
+/**
+ * Internal provider component for pre-created client.
+ */
+function ReplaneProviderWithClient<T extends object>({
+  client,
+  children,
+}: ReplaneProviderWithClientProps<T>) {
+  const value = useMemo<ReplaneContextValue<T>>(() => ({ client }), [client]);
+  return <ReplaneContext.Provider value={value}>{children}</ReplaneContext.Provider>;
+}
+
+/**
+ * Internal provider component for options-based client creation (non-suspense).
+ */
+function ReplaneProviderWithOptions<T extends object>({
+  options,
+  children,
+  loader,
+  onError,
+}: ReplaneProviderWithOptionsProps<T>) {
+  const state = useReplaneClient<T>(options, onError);
+
+  if (state.status === "loading") {
+    return <>{loader ?? null}</>;
+  }
+
+  if (state.status === "error") {
+    // Error was already reported via onError callback
+    // Return loader or null to prevent rendering children without a client
+    return <>{loader ?? null}</>;
+  }
+
+  const value: ReplaneContextValue<T> = { client: state.client };
+  return <ReplaneContext.Provider value={value}>{children}</ReplaneContext.Provider>;
+}
+
+/**
+ * Internal provider component for options-based client creation with Suspense.
+ */
+function ReplaneProviderWithSuspense<T extends object>({
+  options,
+  children,
+}: ReplaneProviderWithOptionsProps<T>) {
+  const client = useReplaneClientSuspense<T>(options);
+  const value = useMemo<ReplaneContextValue<T>>(() => ({ client }), [client]);
+  return <ReplaneContext.Provider value={value}>{children}</ReplaneContext.Provider>;
+}
+
+/**
+ * Provider component that makes a ReplaneClient available to the component tree.
+ *
+ * Can be used in two ways:
+ *
+ * 1. With a pre-created client:
+ * ```tsx
+ * const client = await createReplaneClient({ ... });
+ * <ReplaneProvider client={client}>
+ *   <App />
+ * </ReplaneProvider>
+ * ```
+ *
+ * 2. With options (client managed internally):
+ * ```tsx
+ * <ReplaneProvider
+ *   options={{ baseUrl: '...', sdkKey: '...' }}
+ *   loader={<LoadingSpinner />}
+ * >
+ *   <App />
+ * </ReplaneProvider>
+ * ```
+ *
+ * 3. With Suspense:
+ * ```tsx
+ * <Suspense fallback={<LoadingSpinner />}>
+ *   <ReplaneProvider
+ *     options={{ baseUrl: '...', sdkKey: '...' }}
+ *     suspense
+ *   >
+ *     <App />
+ *   </ReplaneProvider>
+ * </Suspense>
+ * ```
+ */
+export function ReplaneProvider<T extends object>(props: ReplaneProviderProps<T>) {
+  if (hasClient(props)) {
+    return <ReplaneProviderWithClient {...props} />;
+  }
+
+  if (props.suspense) {
+    return <ReplaneProviderWithSuspense {...props} />;
+  }
+
+  return <ReplaneProviderWithOptions {...props} />;
+}