@flagify/react 1.0.0

package/README.md

@@ -0,0 +1,352 @@
+<p align="center">
+  <a href="https://flagify.dev">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://flagify.dev/logo-white.svg" />
+      <source media="(prefers-color-scheme: light)" srcset="https://flagify.dev/logo-color.svg" />
+      <img alt="Flagify" src="https://flagify.dev/logo-color.svg" width="280" />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <strong>Feature flags for modern teams</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@flagify/react"><img src="https://img.shields.io/npm/v/@flagify/react.svg?style=flat-square&color=0D80F9" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@flagify/react"><img src="https://img.shields.io/npm/dm/@flagify/react.svg?style=flat-square&color=0D80F9" alt="npm downloads" /></a>
+  <a href="https://github.com/flagifyhq/react-sdk/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@flagify/react.svg?style=flat-square&color=0D80F9" alt="license" /></a>
+  <a href="https://github.com/flagifyhq/react-sdk"><img src="https://img.shields.io/github/stars/flagifyhq/react-sdk?style=flat-square&color=0D80F9" alt="github stars" /></a>
+</p>
+
+<p align="center">
+  <a href="https://flagify.dev/docs">Documentation</a> &middot;
+  <a href="https://flagify.dev/docs/sdks/react">SDK Reference</a> &middot;
+  <a href="https://github.com/flagifyhq/react-sdk/issues">Issues</a> &middot;
+  <a href="https://flagify.dev">Website</a>
+</p>
+
+---
+
+## Overview
+
+`@flagify/react` is the official React SDK for [Flagify](https://flagify.dev). Idiomatic hooks and a context provider for feature flag evaluation in React applications.
+
+- **Hooks-first** -- `useFlag`, `useVariant`, `useFlagValue` for every use case
+- **Type-safe** -- Full TypeScript generics for flag values
+- **Zero config** -- Wrap with `<FlagifyProvider>`, use hooks anywhere
+- **Lightweight** -- Thin wrapper over [`@flagify/node`](https://github.com/flagifyhq/node-sdk)
+- **React 18+** -- Built for modern React
+- **React Native ready** -- Works in React Native and Expo with zero additional setup
+
+## Table of contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Provider](#provider)
+- [Hooks](#hooks)
+  - [`useFlag`](#useflagflagkey-string-boolean)
+  - [`useVariant`](#usevariantflagkey-string-string--undefined)
+  - [`useFlagValue`](#useflagvaluetflagkey-string-t--undefined)
+  - [`useFlagifyClient`](#useflagifyclient-flagify)
+- [Examples](#examples)
+- [API reference](#api-reference)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+```bash
+# pnpm
+pnpm add @flagify/react
+
+# npm
+npm install @flagify/react
+
+# yarn
+yarn add @flagify/react
+```
+
+> **Peer dependency:** React 18+ is required.
+
+## React Native / Expo
+
+`@flagify/react` is fully compatible with React Native (0.64+) and Expo (SDK 44+). No separate package or polyfills needed.
+
+```bash
+npx expo install @flagify/react
+```
+
+Wrap your root with `<FlagifyProvider>` and use hooks anywhere. For a full getting-started guide, see the [React Native documentation](https://flagify.dev/docs/sdks/react-native).
+
+## Quick start
+
+**1. Wrap your app with the provider**
+
+```tsx
+import { FlagifyProvider } from '@flagify/react'
+
+function App() {
+  return (
+    <FlagifyProvider projectKey="proj_xxx" publicKey="pk_xxx">
+      <YourApp />
+    </FlagifyProvider>
+  )
+}
+```
+
+**2. Use hooks in any component**
+
+```tsx
+import { useFlag } from '@flagify/react'
+
+function Navbar() {
+  const showBanner = useFlag('promo-banner')
+
+  return (
+    <nav>
+      {showBanner && <PromoBanner />}
+    </nav>
+  )
+}
+```
+
+## Provider
+
+### `<FlagifyProvider>`
+
+Initializes the Flagify client and provides it to all child components via React context.
+
+```tsx
+<FlagifyProvider
+  projectKey="proj_xxx"
+  publicKey="pk_xxx"
+  options={{
+    apiUrl: 'https://api.flagify.dev',
+    staleTimeMs: 300_000,
+    user: {
+      id: 'user_123',
+      email: 'mario@example.com',
+      role: 'admin',
+      geolocation: { country: 'US' },
+    },
+  }}
+>
+  {children}
+</FlagifyProvider>
+```
+
+#### Props
+
+All props from [`FlagifyOptions`](https://github.com/flagifyhq/node-sdk#configuration-options) are supported:
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `projectKey` | `string` | Yes | Project identifier from your Flagify workspace |
+| `publicKey` | `string` | Yes | Client-safe publishable API key |
+| `secretKey` | `string` | No | Server-side secret key |
+| `options` | `object` | No | Additional configuration (apiUrl, staleTimeMs, user, realtime) |
+| `children` | `ReactNode` | Yes | Your application tree |
+
+#### Context value
+
+The provider exposes the following context:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `client` | `Flagify \| null` | The underlying Flagify client instance |
+| `isReady` | `boolean` | `true` once the client has been initialized |
+
+## Hooks
+
+### `useFlag(flagKey: string): boolean`
+
+Evaluates a boolean feature flag. Returns `false` if the flag doesn't exist or is disabled.
+
+```tsx
+function Dashboard() {
+  const isNew = useFlag('new-dashboard')
+
+  if (!isNew) return <LegacyDashboard />
+  return <NewDashboard />
+}
+```
+
+---
+
+### `useVariant(flagKey: string): string | undefined`
+
+Returns the string variant of a multivariate flag. Ideal for A/B tests and experiments.
+
+```tsx
+function Onboarding() {
+  const variant = useVariant('onboarding-flow')
+
+  switch (variant) {
+    case 'control':   return <OnboardingClassic />
+    case 'variant-a': return <OnboardingShort />
+    case 'variant-b': return <OnboardingGuided />
+    default:          return <OnboardingClassic />
+  }
+}
+```
+
+---
+
+### `useFlagValue<T>(flagKey: string): T | undefined`
+
+Returns a typed flag value with full TypeScript generics. Supports `number`, `string`, `boolean`, and `JSON` values.
+
+```tsx
+interface ListConfig {
+  maxItems: number
+  showPagination: boolean
+}
+
+function ItemList() {
+  const config = useFlagValue<ListConfig>('list-config')
+
+  return (
+    <ul>
+      {items.slice(0, config?.maxItems ?? 10).map(item => (
+        <li key={item.id}>{item.name}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+---
+
+### `useFlagifyClient(): Flagify`
+
+Direct access to the underlying [`Flagify`](https://github.com/flagifyhq/node-sdk) client instance. Throws if used outside of `<FlagifyProvider>`.
+
+```tsx
+function FeatureGate({ flagKey, children }: { flagKey: string; children: ReactNode }) {
+  const client = useFlagifyClient()
+
+  if (!client.isEnabled(flagKey)) return null
+  return <>{children}</>
+}
+```
+
+## Examples
+
+### Feature gate component
+
+```tsx
+import { useFlag } from '@flagify/react'
+import type { ReactNode } from 'react'
+
+function FeatureGate({ flag, children, fallback }: {
+  flag: string
+  children: ReactNode
+  fallback?: ReactNode
+}) {
+  const isEnabled = useFlag(flag)
+  return <>{isEnabled ? children : fallback}</>
+}
+
+// Usage
+<FeatureGate flag="premium-features" fallback={<UpgradePrompt />}>
+  <PremiumDashboard />
+</FeatureGate>
+```
+
+### A/B test with analytics
+
+```tsx
+import { useVariant } from '@flagify/react'
+import { useEffect } from 'react'
+
+function PricingPage() {
+  const variant = useVariant('pricing-layout')
+
+  useEffect(() => {
+    analytics.track('pricing_viewed', { variant })
+  }, [variant])
+
+  return variant === 'variant-a'
+    ? <PricingCards />
+    : <PricingTable />
+}
+```
+
+### Remote config
+
+```tsx
+import { useFlagValue } from '@flagify/react'
+
+interface ThemeConfig {
+  primaryColor: string
+  borderRadius: number
+  fontFamily: string
+}
+
+function ThemeProvider({ children }: { children: ReactNode }) {
+  const theme = useFlagValue<ThemeConfig>('theme-config')
+
+  const style = {
+    '--primary': theme?.primaryColor ?? '#0D80F9',
+    '--radius': `${theme?.borderRadius ?? 8}px`,
+    '--font': theme?.fontFamily ?? 'Inter',
+  } as React.CSSProperties
+
+  return <div style={style}>{children}</div>
+}
+```
+
+## API reference
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `FlagifyProvider` | Component | Context provider -- wraps your app |
+| `FlagifyContext` | `React.Context` | Raw context (advanced usage) |
+| `useFlag` | Hook | Boolean flag evaluation |
+| `useVariant` | Hook | String variant evaluation |
+| `useFlagValue` | Hook | Typed value evaluation with generics |
+| `useFlagifyClient` | Hook | Direct client access |
+| `FlagifyProviderProps` | Type | Props for `FlagifyProvider` |
+| `FlagifyContextValue` | Type | Shape of the context value |
+
+Types re-exported from `@flagify/node`:
+
+| Export | Description |
+|--------|-------------|
+| `FlagifyOptions` | Client configuration |
+| `FlagifyUser` | User context for targeting |
+| `FlagifyFlaggy` | Flag data structure |
+| `IFlagifyClient` | Client interface |
+
+## Contributing
+
+We welcome contributions. Please open an issue first to discuss what you'd like to change.
+
+```bash
+# Clone
+git clone https://github.com/flagifyhq/react-sdk.git
+cd react-sdk
+
+# Install
+pnpm install
+
+# Development (watch mode)
+pnpm run dev
+
+# Build
+pnpm run build
+
+# Generate barrel exports
+pnpm run generate
+```
+
+## License
+
+MIT -- see [LICENSE](./LICENSE) for details.
+
+---
+
+<p align="center">
+  <sub>Built with care by the <a href="https://flagify.dev">Flagify</a> team</sub>
+</p>

package/dist/index.d.mts

@@ -0,0 +1,32 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import * as _flagify_node from '@flagify/node';
+import { FlagifyOptions, Flagify } from '@flagify/node';
+
+interface FlagifyProviderProps extends FlagifyOptions {
+    children: ReactNode;
+}
+declare function FlagifyProvider({ children, ...config }: FlagifyProviderProps): react_jsx_runtime.JSX.Element;
+
+interface FlagifyContextValue {
+    client: Flagify | null;
+    isReady: boolean;
+    /** Increments on every SSE flag_change event to trigger re-renders */
+    version: number;
+}
+/** Sentinel value — when context equals this, no provider exists */
+declare const NO_PROVIDER: FlagifyContextValue;
+declare const FlagifyContext: react.Context<FlagifyContextValue>;
+
+declare function useFlag(flagKey: string): boolean;
+
+declare function useFlagValue<T>(flagKey: string, fallback: T): T;
+
+declare function useFlagifyClient(): _flagify_node.Flagify | null;
+
+declare function useIsReady(): boolean;
+
+declare function useVariant(flagKey: string, fallback: string): string;
+
+export { FlagifyContext, type FlagifyContextValue, FlagifyProvider, type FlagifyProviderProps, NO_PROVIDER, useFlag, useFlagValue, useFlagifyClient, useIsReady, useVariant };

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import * as _flagify_node from '@flagify/node';
+import { FlagifyOptions, Flagify } from '@flagify/node';
+
+interface FlagifyProviderProps extends FlagifyOptions {
+    children: ReactNode;
+}
+declare function FlagifyProvider({ children, ...config }: FlagifyProviderProps): react_jsx_runtime.JSX.Element;
+
+interface FlagifyContextValue {
+    client: Flagify | null;
+    isReady: boolean;
+    /** Increments on every SSE flag_change event to trigger re-renders */
+    version: number;
+}
+/** Sentinel value — when context equals this, no provider exists */
+declare const NO_PROVIDER: FlagifyContextValue;
+declare const FlagifyContext: react.Context<FlagifyContextValue>;
+
+declare function useFlag(flagKey: string): boolean;
+
+declare function useFlagValue<T>(flagKey: string, fallback: T): T;
+
+declare function useFlagifyClient(): _flagify_node.Flagify | null;
+
+declare function useIsReady(): boolean;
+
+declare function useVariant(flagKey: string, fallback: string): string;
+
+export { FlagifyContext, type FlagifyContextValue, FlagifyProvider, type FlagifyProviderProps, NO_PROVIDER, useFlag, useFlagValue, useFlagifyClient, useIsReady, useVariant };

package/dist/index.js

@@ -0,0 +1,133 @@
+"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, {
+  FlagifyContext: () => FlagifyContext,
+  FlagifyProvider: () => FlagifyProvider,
+  NO_PROVIDER: () => NO_PROVIDER,
+  useFlag: () => useFlag,
+  useFlagValue: () => useFlagValue,
+  useFlagifyClient: () => useFlagifyClient,
+  useIsReady: () => useIsReady,
+  useVariant: () => useVariant
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/FlagifyProvider.tsx
+var import_react2 = require("react");
+var import_node = require("@flagify/node");
+
+// src/context.ts
+var import_react = require("react");
+var NO_PROVIDER = {
+  client: null,
+  isReady: false,
+  version: -1
+};
+var FlagifyContext = (0, import_react.createContext)(NO_PROVIDER);
+
+// src/FlagifyProvider.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+function FlagifyProvider({ children, ...config }) {
+  const [client, setClient] = (0, import_react2.useState)(null);
+  const [isReady, setIsReady] = (0, import_react2.useState)(false);
+  const [version, setVersion] = (0, import_react2.useState)(0);
+  const clientRef = (0, import_react2.useRef)(null);
+  const bumpVersion = (0, import_react2.useCallback)(() => {
+    setVersion((v) => v + 1);
+  }, []);
+  (0, import_react2.useEffect)(() => {
+    const instance = new import_node.Flagify(config);
+    clientRef.current = instance;
+    instance.onFlagChange = bumpVersion;
+    instance.ready().then(() => {
+      if (clientRef.current === instance) {
+        setClient(instance);
+        setIsReady(true);
+      }
+    });
+    return () => {
+      clientRef.current = null;
+      instance.onFlagChange = null;
+      instance.destroy();
+    };
+  }, [config.projectKey, config.publicKey]);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(FlagifyContext.Provider, { value: { client, isReady, version }, children });
+}
+
+// src/useFlag.ts
+var import_react4 = require("react");
+
+// src/useFlagifyClient.ts
+var import_react3 = require("react");
+function useFlagifyClient() {
+  const ctx = (0, import_react3.useContext)(FlagifyContext);
+  if (ctx === NO_PROVIDER) {
+    throw new Error(
+      "useFlagifyClient must be used within a <FlagifyProvider>. Wrap your app with <FlagifyProvider client={client}>."
+    );
+  }
+  return ctx.client;
+}
+
+// src/useFlag.ts
+function useFlag(flagKey) {
+  const { version } = (0, import_react4.useContext)(FlagifyContext);
+  const client = useFlagifyClient();
+  void version;
+  return client?.isEnabled(flagKey) ?? false;
+}
+
+// src/useFlagValue.ts
+var import_react5 = require("react");
+function useFlagValue(flagKey, fallback) {
+  const { version } = (0, import_react5.useContext)(FlagifyContext);
+  const client = useFlagifyClient();
+  void version;
+  return client?.getValue(flagKey, fallback) ?? fallback;
+}
+
+// src/useIsReady.ts
+var import_react6 = require("react");
+function useIsReady() {
+  const { isReady } = (0, import_react6.useContext)(FlagifyContext);
+  return isReady;
+}
+
+// src/useVariant.ts
+var import_react7 = require("react");
+function useVariant(flagKey, fallback) {
+  const { version } = (0, import_react7.useContext)(FlagifyContext);
+  const client = useFlagifyClient();
+  void version;
+  return client?.getVariant(flagKey, fallback) ?? fallback;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FlagifyContext,
+  FlagifyProvider,
+  NO_PROVIDER,
+  useFlag,
+  useFlagValue,
+  useFlagifyClient,
+  useIsReady,
+  useVariant
+});

package/dist/index.mjs

@@ -0,0 +1,99 @@
+// src/FlagifyProvider.tsx
+import { useState, useEffect, useRef, useCallback } from "react";
+import { Flagify } from "@flagify/node";
+
+// src/context.ts
+import { createContext } from "react";
+var NO_PROVIDER = {
+  client: null,
+  isReady: false,
+  version: -1
+};
+var FlagifyContext = createContext(NO_PROVIDER);
+
+// src/FlagifyProvider.tsx
+import { jsx } from "react/jsx-runtime";
+function FlagifyProvider({ children, ...config }) {
+  const [client, setClient] = useState(null);
+  const [isReady, setIsReady] = useState(false);
+  const [version, setVersion] = useState(0);
+  const clientRef = useRef(null);
+  const bumpVersion = useCallback(() => {
+    setVersion((v) => v + 1);
+  }, []);
+  useEffect(() => {
+    const instance = new Flagify(config);
+    clientRef.current = instance;
+    instance.onFlagChange = bumpVersion;
+    instance.ready().then(() => {
+      if (clientRef.current === instance) {
+        setClient(instance);
+        setIsReady(true);
+      }
+    });
+    return () => {
+      clientRef.current = null;
+      instance.onFlagChange = null;
+      instance.destroy();
+    };
+  }, [config.projectKey, config.publicKey]);
+  return /* @__PURE__ */ jsx(FlagifyContext.Provider, { value: { client, isReady, version }, children });
+}
+
+// src/useFlag.ts
+import { useContext as useContext2 } from "react";
+
+// src/useFlagifyClient.ts
+import { useContext } from "react";
+function useFlagifyClient() {
+  const ctx = useContext(FlagifyContext);
+  if (ctx === NO_PROVIDER) {
+    throw new Error(
+      "useFlagifyClient must be used within a <FlagifyProvider>. Wrap your app with <FlagifyProvider client={client}>."
+    );
+  }
+  return ctx.client;
+}
+
+// src/useFlag.ts
+function useFlag(flagKey) {
+  const { version } = useContext2(FlagifyContext);
+  const client = useFlagifyClient();
+  void version;
+  return client?.isEnabled(flagKey) ?? false;
+}
+
+// src/useFlagValue.ts
+import { useContext as useContext3 } from "react";
+function useFlagValue(flagKey, fallback) {
+  const { version } = useContext3(FlagifyContext);
+  const client = useFlagifyClient();
+  void version;
+  return client?.getValue(flagKey, fallback) ?? fallback;
+}
+
+// src/useIsReady.ts
+import { useContext as useContext4 } from "react";
+function useIsReady() {
+  const { isReady } = useContext4(FlagifyContext);
+  return isReady;
+}
+
+// src/useVariant.ts
+import { useContext as useContext5 } from "react";
+function useVariant(flagKey, fallback) {
+  const { version } = useContext5(FlagifyContext);
+  const client = useFlagifyClient();
+  void version;
+  return client?.getVariant(flagKey, fallback) ?? fallback;
+}
+export {
+  FlagifyContext,
+  FlagifyProvider,
+  NO_PROVIDER,
+  useFlag,
+  useFlagValue,
+  useFlagifyClient,
+  useIsReady,
+  useVariant
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@flagify/react",
+  "version": "1.0.0",
+  "description": "React SDK for Flagify — hooks and provider for feature flag evaluation.",
+  "author": "Mario Campbell R <mario@mariocampbellr.com>",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "dependencies": {
+    "@flagify/node": "1.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^14",
+    "@types/react": "^18.2.0",
+    "jsdom": "^29.0.1",
+    "react": "^18.2.0",
+    "react-dom": "18"
+  },
+  "keywords": [
+    "feature-flags",
+    "flagify",
+    "react",
+    "hooks"
+  ],
+  "homepage": "https://flagify.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flagifyhq/javascript",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/flagifyhq/javascript/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "generate": "barrelsby -c ./barrelsby.json",
+    "build": "pnpm run generate && tsup src/index.ts --format esm,cjs --dts",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "test": "vitest run",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}