@featureflip/react 1.0.0

package/README.md

@@ -0,0 +1,112 @@
+# @featureflip/react-sdk
+
+React bindings for Featureflip feature flag evaluation.
+
+## Installation
+
+```bash
+npm install @featureflip/react-sdk @featureflip/browser-sdk
+```
+
+## Quick Start
+
+Wrap your app with `FeatureflipProvider`, then use `useFeatureFlag` in any component.
+
+```tsx
+import { FeatureflipProvider, useFeatureFlag } from '@featureflip/react-sdk';
+
+function App() {
+  return (
+    <FeatureflipProvider clientKey="your-client-sdk-key">
+      <Banner />
+    </FeatureflipProvider>
+  );
+}
+
+function Banner() {
+  const showBanner = useFeatureFlag('show-banner', false);
+  if (!showBanner) return null;
+  return <div>New feature available!</div>;
+}
+```
+
+## Provider Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `clientKey` | `string` | **(required)** | Client SDK key |
+| `context` | `Record<string, unknown>` | `undefined` | Evaluation context (user attributes) |
+| `baseUrl` | `string` | `undefined` | Evaluation API base URL |
+| `streaming` | `boolean` | `undefined` | Enable SSE streaming |
+
+The provider creates a `FeatureflipClient` internally and calls `initialize()` on mount. It cleans up (calls `close()`) on unmount.
+
+## Hooks
+
+### `useFeatureFlag<T>(key: string, defaultValue: T): T`
+
+Returns the evaluated value of a flag. The component re-renders automatically when the flag value changes via streaming or `identify()`. The type of `defaultValue` determines which variation method is called (`boolVariation`, `stringVariation`, `numberVariation`, or `jsonVariation`).
+
+```tsx
+const enabled = useFeatureFlag('new-checkout', false);
+const color = useFeatureFlag('button-color', 'blue');
+const limit = useFeatureFlag('rate-limit', 100);
+const config = useFeatureFlag('ui-config', { sidebar: true });
+```
+
+### `useFeatureflipStatus(): { isReady, isError, error }`
+
+Returns the initialization status of the client. Useful for showing loading states.
+
+```tsx
+function App() {
+  const { isReady, isError, error } = useFeatureflipStatus();
+
+  if (isError) return <div>Error: {error?.message}</div>;
+  if (!isReady) return <div>Loading...</div>;
+
+  return <Main />;
+}
+```
+
+### `useFeatureflipClient(): FeatureflipClient`
+
+Returns the underlying `FeatureflipClient` instance for direct access (e.g., calling `identify`).
+
+## Identify on Login
+
+When the context prop changes, the provider automatically calls `identify()` and re-evaluates all flags. You can also call `identify` directly.
+
+```tsx
+function LoginPage() {
+  const client = useFeatureflipClient();
+
+  async function handleLogin(userId: string) {
+    // ... authenticate ...
+    await client.identify({ user_id: userId, plan: 'pro' });
+  }
+
+  return <button onClick={() => handleLogin('123')}>Log in</button>;
+}
+```
+
+## Testing
+
+Use `TestFeatureflipProvider` to supply predetermined flag values in tests -- no network calls, no initialization delay.
+
+```tsx
+import { TestFeatureflipProvider } from '@featureflip/react-sdk';
+import { render, screen } from '@testing-library/react';
+
+test('renders banner when flag is on', () => {
+  render(
+    <TestFeatureflipProvider flags={{ 'show-banner': true }}>
+      <Banner />
+    </TestFeatureflipProvider>,
+  );
+
+  expect(screen.getByText('New feature available!')).toBeInTheDocument();
+});
+```
+
+`TestFeatureflipProvider` uses `FeatureflipClient.forTesting()` internally and sets `isReady: true` immediately.

package/dist/__tests__/hooks.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=hooks.test.d.ts.map

package/dist/__tests__/hooks.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/hooks.test.tsx"],"names":[],"mappings":""}

package/dist/__tests__/provider.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=provider.test.d.ts.map

package/dist/__tests__/provider.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/provider.test.tsx"],"names":[],"mappings":""}

package/dist/context.d.ts

@@ -0,0 +1,9 @@
+import { FeatureflipClient } from '../../browser-sdk/src';
+export interface FeatureflipContextValue {
+    client: FeatureflipClient;
+    isReady: boolean;
+    isError: boolean;
+    error: Error | null;
+}
+export declare const FeatureflipContext: import('react').Context<FeatureflipContextValue | null>;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAED,eAAO,MAAM,kBAAkB,yDAAsD,CAAC"}

package/dist/hooks.d.ts

@@ -0,0 +1,9 @@
+import { FeatureflipClient } from '../../browser-sdk/src';
+export declare function useFeatureFlag<T>(key: string, defaultValue: T): T;
+export declare function useFeatureflipClient(): FeatureflipClient;
+export declare function useFeatureflipStatus(): {
+    isReady: boolean;
+    isError: boolean;
+    error: Error | null;
+};
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AA0B9D,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,GAAG,CAAC,CAmDjE;AAED,wBAAgB,oBAAoB,IAAI,iBAAiB,CAGxD;AAED,wBAAgB,oBAAoB,IAAI;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB,CAGA"}

package/dist/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`./testing-CXh0WG3c.cjs`);let t=require(`react`),n=require(`@featureflip/browser`),r=require(`react/jsx-runtime`);function i({clientKey:i,context:a,baseUrl:o,streaming:s,children:c}){let l=(0,t.useRef)(null),[u,d]=(0,t.useState)(0),[f,p]=(0,t.useState)(!1),[m,h]=(0,t.useState)(!1),[g,_]=(0,t.useState)(null),v=(0,t.useRef)(``);l.current===null&&(l.current=new n.FeatureflipClient({clientKey:i,baseUrl:o,context:a,streaming:s})),(0,t.useEffect)(()=>{l.current||(l.current=new n.FeatureflipClient({clientKey:i,baseUrl:o,context:a,streaming:s}),p(!1),h(!1),_(null),d(e=>e+1));let e=l.current,t=()=>p(!0),r=e=>{h(!0),_(e instanceof Error?e:Error(String(e)))};return e.on(`ready`,t),e.on(`error`,r),e.initialize().catch(r),()=>{e.off(`ready`,t),e.off(`error`,r),e.close(),l.current=null}},[]),(0,t.useEffect)(()=>{let e=JSON.stringify(a??{});if(v.current===``){v.current=e;return}e!==v.current&&(v.current=e,l.current?.identify(a??{}).catch(()=>{}))},[a]);let y={client:l.current,isReady:f,isError:m,error:g};return(0,r.jsx)(e.n.Provider,{value:y,children:c})}function a(){let n=(0,t.useContext)(e.n);if(n===null)throw Error(`useFeatureFlag must be used within a <FeatureflipProvider>`);return n}function o(e,t,n){switch(typeof n){case`boolean`:return e.boolVariation(t,n);case`string`:return e.stringVariation(t,n);case`number`:return e.numberVariation(t,n);default:return e.jsonVariation(t,n)}}function s(e,n){let{client:r}=a(),i=(0,t.useRef)(n);i.current=n;let s=(0,t.useRef)(void 0),c=(0,t.useRef)(void 0),l=(0,t.useCallback)(e=>{let t=()=>e();return r.on(`change`,t),()=>r.off(`change`,t)},[r]),u=(0,t.useCallback)(()=>{let t=o(r,e,i.current);if(Object.is(t,s.current))return s.current;if(typeof t!=`object`||!t)return s.current=t,t;try{let e=JSON.stringify(t);if(s.current!==void 0&&e===c.current)return s.current;s.current=t,c.current=e}catch{s.current=t}return t},[r,e]);return(0,t.useSyncExternalStore)(l,u,u)}function c(){let{client:e}=a();return e}function l(){let{isReady:e,isError:t,error:n}=a();return{isReady:e,isError:t,error:n}}exports.FeatureflipContext=e.n,exports.FeatureflipProvider=i,exports.TestFeatureflipProvider=e.t,exports.useFeatureFlag=s,exports.useFeatureflipClient=c,exports.useFeatureflipStatus=l;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { FeatureflipProvider } from './provider';
+export type { FeatureflipProviderProps } from './provider';
+export { useFeatureFlag, useFeatureflipClient, useFeatureflipStatus } from './hooks';
+export { TestFeatureflipProvider } from './testing';
+export { FeatureflipContext } from './context';
+export type { FeatureflipContextValue } from './context';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,YAAY,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AACrF,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,YAAY,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,94 @@
+import { n as e, t } from "./testing-D-nDtDyw.js";
+import { useCallback as n, useContext as r, useEffect as i, useRef as a, useState as o, useSyncExternalStore as s } from "react";
+import { FeatureflipClient as c } from "@featureflip/browser";
+import { jsx as l } from "react/jsx-runtime";
+//#region src/provider.tsx
+function u({ clientKey: t, context: n, baseUrl: r, streaming: s, children: u }) {
+	let d = a(null), [f, p] = o(0), [m, h] = o(!1), [g, _] = o(!1), [v, y] = o(null), b = a("");
+	d.current === null && (d.current = new c({
+		clientKey: t,
+		baseUrl: r,
+		context: n,
+		streaming: s
+	})), i(() => {
+		d.current || (d.current = new c({
+			clientKey: t,
+			baseUrl: r,
+			context: n,
+			streaming: s
+		}), h(!1), _(!1), y(null), p((e) => e + 1));
+		let e = d.current, i = () => h(!0), a = (e) => {
+			_(!0), y(e instanceof Error ? e : Error(String(e)));
+		};
+		return e.on("ready", i), e.on("error", a), e.initialize().catch(a), () => {
+			e.off("ready", i), e.off("error", a), e.close(), d.current = null;
+		};
+	}, []), i(() => {
+		let e = JSON.stringify(n ?? {});
+		if (b.current === "") {
+			b.current = e;
+			return;
+		}
+		e !== b.current && (b.current = e, d.current?.identify(n ?? {}).catch(() => {}));
+	}, [n]);
+	let x = {
+		client: d.current,
+		isReady: m,
+		isError: g,
+		error: v
+	};
+	return /* @__PURE__ */ l(e.Provider, {
+		value: x,
+		children: u
+	});
+}
+//#endregion
+//#region src/hooks.ts
+function d() {
+	let t = r(e);
+	if (t === null) throw Error("useFeatureFlag must be used within a <FeatureflipProvider>");
+	return t;
+}
+function f(e, t, n) {
+	switch (typeof n) {
+		case "boolean": return e.boolVariation(t, n);
+		case "string": return e.stringVariation(t, n);
+		case "number": return e.numberVariation(t, n);
+		default: return e.jsonVariation(t, n);
+	}
+}
+function p(e, t) {
+	let { client: r } = d(), i = a(t);
+	i.current = t;
+	let o = a(void 0), c = a(void 0), l = n((e) => {
+		let t = () => e();
+		return r.on("change", t), () => r.off("change", t);
+	}, [r]), u = n(() => {
+		let t = f(r, e, i.current);
+		if (Object.is(t, o.current)) return o.current;
+		if (typeof t != "object" || !t) return o.current = t, t;
+		try {
+			let e = JSON.stringify(t);
+			if (o.current !== void 0 && e === c.current) return o.current;
+			o.current = t, c.current = e;
+		} catch {
+			o.current = t;
+		}
+		return t;
+	}, [r, e]);
+	return s(l, u, u);
+}
+function m() {
+	let { client: e } = d();
+	return e;
+}
+function h() {
+	let { isReady: e, isError: t, error: n } = d();
+	return {
+		isReady: e,
+		isError: t,
+		error: n
+	};
+}
+//#endregion
+export { e as FeatureflipContext, u as FeatureflipProvider, t as TestFeatureflipProvider, p as useFeatureFlag, m as useFeatureflipClient, h as useFeatureflipStatus };

package/dist/provider.d.ts

@@ -0,0 +1,10 @@
+import { ReactNode } from 'react';
+export interface FeatureflipProviderProps {
+    clientKey: string;
+    context?: Record<string, unknown>;
+    baseUrl?: string;
+    streaming?: boolean;
+    children: ReactNode;
+}
+export declare function FeatureflipProvider({ clientKey, context, baseUrl, streaming, children, }: FeatureflipProviderProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAIpE,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,wBAAgB,mBAAmB,CAAC,EAClC,SAAS,EACT,OAAO,EACP,OAAO,EACP,SAAS,EACT,QAAQ,GACT,EAAE,wBAAwB,2CAmF1B"}

package/dist/testing-CXh0WG3c.cjs

@@ -0,0 +1 @@
+let e=require(`react`),t=require(`@featureflip/browser`),n=require(`react/jsx-runtime`);var r=(0,e.createContext)(null);function i({flags:e,children:i}){let a=t.FeatureflipClient.forTesting(e);return(0,n.jsx)(r.Provider,{value:{client:a,isReady:!0,isError:!1,error:null},children:i})}Object.defineProperty(exports,`n`,{enumerable:!0,get:function(){return r}}),Object.defineProperty(exports,`t`,{enumerable:!0,get:function(){return i}});

package/dist/testing-D-nDtDyw.js

@@ -0,0 +1,21 @@
+import { createContext as e } from "react";
+import { FeatureflipClient as t } from "@featureflip/browser";
+import { jsx as n } from "react/jsx-runtime";
+//#region src/context.ts
+var r = e(null);
+//#endregion
+//#region src/testing.tsx
+function i({ flags: e, children: i }) {
+	let a = t.forTesting(e);
+	return /* @__PURE__ */ n(r.Provider, {
+		value: {
+			client: a,
+			isReady: !0,
+			isError: !1,
+			error: null
+		},
+		children: i
+	});
+}
+//#endregion
+export { r as n, i as t };

package/dist/testing.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`./testing-CXh0WG3c.cjs`);exports.TestFeatureflipProvider=e.t;

package/dist/testing.d.ts

@@ -0,0 +1,8 @@
+import { ReactNode } from 'react';
+interface TestFeatureflipProviderProps {
+    flags: Record<string, unknown>;
+    children: ReactNode;
+}
+export declare function TestFeatureflipProvider({ flags, children }: TestFeatureflipProviderProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIvC,UAAU,4BAA4B;IACpC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,wBAAgB,uBAAuB,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,4BAA4B,2CAOxF"}

package/dist/testing.js

@@ -0,0 +1,2 @@
+import { t as e } from "./testing-D-nDtDyw.js";
+export { e as TestFeatureflipProvider };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@featureflip/react",
+  "version": "1.0.0",
+  "description": "React SDK for Featureflip - React bindings for feature flag evaluation",
+  "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"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "require": "./dist/testing.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "license": "Apache-2.0",
+  "homepage": "https://featureflip.io/docs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@featureflip/browser": "^1.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "devDependencies": {
+    "@featureflip/browser": "file:../browser-sdk",
+    "@testing-library/react": "^16.0.0",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "jsdom": "^28.0.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "typescript": "^5.9.0",
+    "vite": "^8.0.0",
+    "vite-plugin-dts": "^4.0.0",
+    "vitest": "^4.1.0"
+  }
+}