featuretoggle-sdk-react 1.0.0

package/README.md

@@ -0,0 +1,43 @@
+# featuretoggle-sdk-react
+
+React adapter for [featuretoggle-sdk-typescript](https://www.npmjs.com/package/featuretoggle-sdk-typescript) — `FeatureToggleProvider`, `useFeature`, and `useFeatureToggle`.
+
+## Install
+
+```bash
+bun add featuretoggle-sdk-react featuretoggle-sdk-typescript react
+```
+
+Peers: `react` (≥18), `featuretoggle-sdk-typescript` (^1.0.0).
+
+## Quick start
+
+```tsx
+import { FeatureToggleProvider, useFeature } from "featuretoggle-sdk-react";
+
+function App() {
+  return (
+    <FeatureToggleProvider apiKey={import.meta.env.VITE_FT_API_KEY}>
+      <Checkout />
+    </FeatureToggleProvider>
+  );
+}
+
+function Checkout() {
+  const { enabled, loading } = useFeature("new-checkout");
+  if (loading) return null;
+  return enabled ? <NewCheckout /> : <LegacyCheckout />;
+}
+```
+
+## Integration patterns
+
+See the [integration cookbook](https://github.com/feature-toggle/feature-toggle-monorepo/blob/main/docs/17-sdk-integration-patterns.md) for SSR seed, BYO client, `autoInit={false}`, and more (patterns I–N).
+
+## API
+
+- `<FeatureToggleProvider>` — `apiKey`, optional `client`, `initialFeatures`, `initialEtag`, `autoInit` (default `true`)
+- `useFeature(key)` — `{ enabled, value, loading, error }`
+- `useFeatureToggle()` — `{ init, refresh, getFeatures, loading, error }`
+
+Import `FeatureResponse` from `featuretoggle-sdk-typescript` — not re-exported from this package.

package/dist/index.cjs

@@ -0,0 +1,166 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  FeatureToggleProvider: () => FeatureToggleProvider,
+  useFeature: () => useFeature,
+  useFeatureToggle: () => useFeatureToggle
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/provider.tsx
+var import_featuretoggle_sdk_typescript = require("featuretoggle-sdk-typescript");
+var import_react2 = require("react");
+
+// src/context.ts
+var import_react = require("react");
+var FeatureToggleContext = (0, import_react.createContext)(
+  null
+);
+
+// src/provider.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+function useFeatureToggleContext() {
+  const value = (0, import_react2.useContext)(FeatureToggleContext);
+  if (!value) {
+    throw new Error("useFeature must be used within FeatureToggleProvider");
+  }
+  return value;
+}
+function isSeeded(initialFeatures) {
+  return initialFeatures !== void 0;
+}
+function FeatureToggleProvider({
+  apiKey,
+  client: clientProp,
+  initialFeatures,
+  initialEtag,
+  autoInit = true,
+  pollInterval: _pollInterval,
+  children
+}) {
+  const ownsClient = clientProp === void 0;
+  const seeded = isSeeded(initialFeatures);
+  const initGenerationRef = (0, import_react2.useRef)(0);
+  const clientRef = (0, import_react2.useRef)(null);
+  const apiKeyRef = (0, import_react2.useRef)(apiKey);
+  if (clientProp) {
+    clientRef.current = null;
+  } else if (apiKey) {
+    if (!clientRef.current || apiKeyRef.current !== apiKey) {
+      clientRef.current?.close();
+      clientRef.current = new import_featuretoggle_sdk_typescript.FeatureToggle({
+        apiKey,
+        initialFeatures,
+        initialEtag
+      });
+      apiKeyRef.current = apiKey;
+    }
+  } else {
+    throw new Error("FeatureToggleProvider requires apiKey or client");
+  }
+  const client = clientProp ?? clientRef.current;
+  const [loading, setLoading] = (0, import_react2.useState)(() => !seeded);
+  const [error, setError] = (0, import_react2.useState)(null);
+  const runInit = (0, import_react2.useCallback)(async () => {
+    const generation = ++initGenerationRef.current;
+    setError(null);
+    if (!seeded) {
+      setLoading(true);
+    }
+    try {
+      await client.init();
+      if (initGenerationRef.current !== generation) return;
+      setLoading(false);
+    } catch (unknownError) {
+      if (initGenerationRef.current !== generation) return;
+      const nextError = unknownError instanceof Error ? unknownError : new Error(String(unknownError));
+      setError(nextError);
+      setLoading(false);
+      throw nextError;
+    }
+  }, [client, seeded]);
+  const refresh = (0, import_react2.useCallback)(async () => {
+    await client.refresh();
+  }, [client]);
+  (0, import_react2.useEffect)(() => {
+    if (!autoInit) return;
+    void runInit().catch(() => void 0);
+  }, [autoInit, runInit]);
+  (0, import_react2.useEffect)(() => {
+    if (!ownsClient) return;
+    return () => {
+      initGenerationRef.current += 1;
+      clientRef.current?.close();
+      clientRef.current = null;
+    };
+  }, [ownsClient]);
+  const contextValue = (0, import_react2.useMemo)(
+    () => ({
+      client,
+      loading,
+      error,
+      init: runInit,
+      refresh
+    }),
+    [client, loading, error, runInit, refresh]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(FeatureToggleContext.Provider, { value: contextValue, children });
+}
+function useFeature(key) {
+  const { client, loading, error } = useFeatureToggleContext();
+  const snapshot = (0, import_react2.useSyncExternalStore)(
+    (listener) => client.subscribe(listener),
+    () => JSON.stringify({
+      enabled: client.isEnabled(key),
+      value: client.getValue(key)
+    }),
+    () => JSON.stringify({ enabled: false, value: void 0 })
+  );
+  const parsed = JSON.parse(snapshot);
+  return {
+    enabled: parsed.enabled,
+    value: parsed.value,
+    loading,
+    error
+  };
+}
+function useFeatureToggle() {
+  const { client, loading, error, init, refresh } = useFeatureToggleContext();
+  (0, import_react2.useSyncExternalStore)(
+    (listener) => client.subscribe(listener),
+    () => JSON.stringify(client.getFeatures()),
+    () => "[]"
+  );
+  return {
+    init,
+    refresh,
+    getFeatures: (options) => client.getFeatures(options),
+    loading,
+    error
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FeatureToggleProvider,
+  useFeature,
+  useFeatureToggle
+});

package/dist/index.d.cts

@@ -0,0 +1,38 @@
+import * as react from 'react';
+import { FeatureToggle, FeatureResponse } from 'featuretoggle-sdk-typescript';
+
+type FeatureToggleProviderProps = {
+    apiKey?: string;
+    client?: FeatureToggle;
+    pollInterval?: number;
+    initialFeatures?: FeatureResponse[];
+    initialEtag?: string;
+    autoInit?: boolean;
+    children: React.ReactNode;
+};
+type UseFeatureResult<T = unknown> = {
+    enabled: boolean;
+    value: T | undefined;
+    loading: boolean;
+    error: Error | null;
+};
+type UseFeatureToggleResult = {
+    init: () => Promise<void>;
+    refresh: () => Promise<void>;
+    getFeatures: (options?: Parameters<FeatureToggle["getFeatures"]>[0]) => FeatureResponse[];
+    loading: boolean;
+    error: Error | null;
+};
+type FeatureToggleContextValue = {
+    client: FeatureToggle;
+    loading: boolean;
+    error: Error | null;
+    init: () => Promise<void>;
+    refresh: () => Promise<void>;
+};
+
+declare function FeatureToggleProvider({ apiKey, client: clientProp, initialFeatures, initialEtag, autoInit, pollInterval: _pollInterval, children, }: FeatureToggleProviderProps): react.JSX.Element;
+declare function useFeature<T = unknown>(key: string): UseFeatureResult<T>;
+declare function useFeatureToggle(): UseFeatureToggleResult;
+
+export { type FeatureToggleContextValue, FeatureToggleProvider, type FeatureToggleProviderProps, type UseFeatureResult, type UseFeatureToggleResult, useFeature, useFeatureToggle };

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import * as react from 'react';
+import { FeatureToggle, FeatureResponse } from 'featuretoggle-sdk-typescript';
+
+type FeatureToggleProviderProps = {
+    apiKey?: string;
+    client?: FeatureToggle;
+    pollInterval?: number;
+    initialFeatures?: FeatureResponse[];
+    initialEtag?: string;
+    autoInit?: boolean;
+    children: React.ReactNode;
+};
+type UseFeatureResult<T = unknown> = {
+    enabled: boolean;
+    value: T | undefined;
+    loading: boolean;
+    error: Error | null;
+};
+type UseFeatureToggleResult = {
+    init: () => Promise<void>;
+    refresh: () => Promise<void>;
+    getFeatures: (options?: Parameters<FeatureToggle["getFeatures"]>[0]) => FeatureResponse[];
+    loading: boolean;
+    error: Error | null;
+};
+type FeatureToggleContextValue = {
+    client: FeatureToggle;
+    loading: boolean;
+    error: Error | null;
+    init: () => Promise<void>;
+    refresh: () => Promise<void>;
+};
+
+declare function FeatureToggleProvider({ apiKey, client: clientProp, initialFeatures, initialEtag, autoInit, pollInterval: _pollInterval, children, }: FeatureToggleProviderProps): react.JSX.Element;
+declare function useFeature<T = unknown>(key: string): UseFeatureResult<T>;
+declare function useFeatureToggle(): UseFeatureToggleResult;
+
+export { type FeatureToggleContextValue, FeatureToggleProvider, type FeatureToggleProviderProps, type UseFeatureResult, type UseFeatureToggleResult, useFeature, useFeatureToggle };

package/dist/index.js

@@ -0,0 +1,147 @@
+// src/provider.tsx
+import {
+  FeatureToggle
+} from "featuretoggle-sdk-typescript";
+import {
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore
+} from "react";
+
+// src/context.ts
+import { createContext } from "react";
+var FeatureToggleContext = createContext(
+  null
+);
+
+// src/provider.tsx
+import { jsx } from "react/jsx-runtime";
+function useFeatureToggleContext() {
+  const value = useContext(FeatureToggleContext);
+  if (!value) {
+    throw new Error("useFeature must be used within FeatureToggleProvider");
+  }
+  return value;
+}
+function isSeeded(initialFeatures) {
+  return initialFeatures !== void 0;
+}
+function FeatureToggleProvider({
+  apiKey,
+  client: clientProp,
+  initialFeatures,
+  initialEtag,
+  autoInit = true,
+  pollInterval: _pollInterval,
+  children
+}) {
+  const ownsClient = clientProp === void 0;
+  const seeded = isSeeded(initialFeatures);
+  const initGenerationRef = useRef(0);
+  const clientRef = useRef(null);
+  const apiKeyRef = useRef(apiKey);
+  if (clientProp) {
+    clientRef.current = null;
+  } else if (apiKey) {
+    if (!clientRef.current || apiKeyRef.current !== apiKey) {
+      clientRef.current?.close();
+      clientRef.current = new FeatureToggle({
+        apiKey,
+        initialFeatures,
+        initialEtag
+      });
+      apiKeyRef.current = apiKey;
+    }
+  } else {
+    throw new Error("FeatureToggleProvider requires apiKey or client");
+  }
+  const client = clientProp ?? clientRef.current;
+  const [loading, setLoading] = useState(() => !seeded);
+  const [error, setError] = useState(null);
+  const runInit = useCallback(async () => {
+    const generation = ++initGenerationRef.current;
+    setError(null);
+    if (!seeded) {
+      setLoading(true);
+    }
+    try {
+      await client.init();
+      if (initGenerationRef.current !== generation) return;
+      setLoading(false);
+    } catch (unknownError) {
+      if (initGenerationRef.current !== generation) return;
+      const nextError = unknownError instanceof Error ? unknownError : new Error(String(unknownError));
+      setError(nextError);
+      setLoading(false);
+      throw nextError;
+    }
+  }, [client, seeded]);
+  const refresh = useCallback(async () => {
+    await client.refresh();
+  }, [client]);
+  useEffect(() => {
+    if (!autoInit) return;
+    void runInit().catch(() => void 0);
+  }, [autoInit, runInit]);
+  useEffect(() => {
+    if (!ownsClient) return;
+    return () => {
+      initGenerationRef.current += 1;
+      clientRef.current?.close();
+      clientRef.current = null;
+    };
+  }, [ownsClient]);
+  const contextValue = useMemo(
+    () => ({
+      client,
+      loading,
+      error,
+      init: runInit,
+      refresh
+    }),
+    [client, loading, error, runInit, refresh]
+  );
+  return /* @__PURE__ */ jsx(FeatureToggleContext.Provider, { value: contextValue, children });
+}
+function useFeature(key) {
+  const { client, loading, error } = useFeatureToggleContext();
+  const snapshot = useSyncExternalStore(
+    (listener) => client.subscribe(listener),
+    () => JSON.stringify({
+      enabled: client.isEnabled(key),
+      value: client.getValue(key)
+    }),
+    () => JSON.stringify({ enabled: false, value: void 0 })
+  );
+  const parsed = JSON.parse(snapshot);
+  return {
+    enabled: parsed.enabled,
+    value: parsed.value,
+    loading,
+    error
+  };
+}
+function useFeatureToggle() {
+  const { client, loading, error, init, refresh } = useFeatureToggleContext();
+  useSyncExternalStore(
+    (listener) => client.subscribe(listener),
+    () => JSON.stringify(client.getFeatures()),
+    () => "[]"
+  );
+  return {
+    init,
+    refresh,
+    getFeatures: (options) => client.getFeatures(options),
+    loading,
+    error
+  };
+}
+export {
+  FeatureToggleProvider,
+  useFeature,
+  useFeatureToggle
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "featuretoggle-sdk-react",
+  "version": "1.0.0",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/feature-toggle/sdk-react.git"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "bun run --filter featuretoggle-sdk-typescript build && bun test --preload ./test/preload.ts",
+    "lint": "eslint .",
+    "check-types": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "featuretoggle-sdk-typescript": "^1.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.28.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.2.0",
+    "@happy-dom/global-registrator": "^20.0.10",
+    "eslint": "^9.28.0",
+    "featuretoggle-sdk-typescript": "workspace:*",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.33.1"
+  }
+}