@variantlab/react 0.1.0 → 0.1.2

package/README.md

@@ -1,11 +1,175 @@
 # @variantlab/react
 
-React hooks and components for variantlab.
+> React hooks and components for variantlab — the universal, zero-dependency A/B testing toolkit.
 
-> **Status:** Phase 1 — Pre-alpha. Not ready for production use.
+![npm version](https://img.shields.io/npm/v/@variantlab/react/alpha?label=npm&color=blue)
+![bundle size](https://img.shields.io/badge/gzip-%3C2KB-brightgreen)
 
-## Peer dependencies
+## Install
 
-- `react` `^18.2.0 || ^19.0.0`
+```bash
+npm install @variantlab/core@alpha @variantlab/react@alpha
+```
 
-See the [root README](../../README.md) for project overview, motivation, and roadmap.
+**Peer dependencies:** `react ^18.2.0 || ^19.0.0`
+
+## Quick start
+
+### 1. Create the engine and wrap your app
+
+```tsx
+import { createEngine } from "@variantlab/core";
+import { VariantLabProvider } from "@variantlab/react";
+import experiments from "./experiments.json";
+
+const engine = createEngine(experiments);
+
+export default function App() {
+  return (
+    <VariantLabProvider engine={engine}>
+      <YourApp />
+    </VariantLabProvider>
+  );
+}
+```
+
+### 2. Use hooks
+
+```tsx
+import { useVariant, useVariantValue } from "@variantlab/react";
+
+function HeroSection() {
+  // Get the assigned variant ID
+  const variant = useVariant("hero-layout"); // "centered" | "split"
+
+  return variant === "split" ? <SplitHero /> : <CenteredHero />;
+}
+
+function CheckoutButton() {
+  // Get a value experiment's value directly
+  const copy = useVariantValue<string>("cta-copy"); // "Buy now" | "Get started"
+
+  return <button>{copy}</button>;
+}
+```
+
+### 3. Or use components
+
+```tsx
+import { Variant, VariantValue } from "@variantlab/react";
+
+function HeroSection() {
+  return (
+    <Variant experimentId="hero-layout" fallback={<CenteredHero />}>
+      {{
+        centered: <CenteredHero />,
+        split: <SplitHero />,
+      }}
+    </Variant>
+  );
+}
+
+function CheckoutButton() {
+  return (
+    <VariantValue experimentId="cta-copy">
+      {(value) => <button>{value}</button>}
+    </VariantValue>
+  );
+}
+```
+
+## Hooks API
+
+### `useVariant(experimentId)`
+
+Returns the assigned variant ID for a render experiment.
+
+```tsx
+const variantId = useVariant("hero-layout"); // "centered" | "split"
+```
+
+### `useVariantValue<T>(experimentId)`
+
+Returns the value of a value experiment.
+
+```tsx
+const copy = useVariantValue<string>("cta-copy"); // "Buy now"
+const price = useVariantValue<number>("pricing"); // 9.99
+```
+
+### `useExperiment(experimentId)`
+
+Returns the full experiment state including metadata.
+
+```tsx
+const { variantId, experiment, isOverridden } = useExperiment("hero-layout");
+```
+
+### `useSetVariant()`
+
+Returns a function to override variant assignments (useful for debug UIs).
+
+```tsx
+const setVariant = useSetVariant();
+setVariant("hero-layout", "split"); // force split variant
+```
+
+### `useVariantLabEngine()`
+
+Returns the engine instance directly.
+
+```tsx
+const engine = useVariantLabEngine();
+engine.resetAll();
+```
+
+### `useRouteExperiments()`
+
+Returns experiments that target the current route.
+
+```tsx
+const experiments = useRouteExperiments();
+```
+
+## Components
+
+### `<Variant>`
+
+Renders the matching variant child by ID.
+
+```tsx
+<Variant experimentId="hero-layout" fallback={<Default />}>
+  {{
+    centered: <CenteredHero />,
+    split: <SplitHero />,
+  }}
+</Variant>
+```
+
+### `<VariantValue>`
+
+Render-prop component for value experiments.
+
+```tsx
+<VariantValue experimentId="cta-copy">
+  {(value) => <span>{value}</span>}
+</VariantValue>
+```
+
+### `<VariantErrorBoundary>`
+
+Error boundary with crash-rollback integration. If a variant crashes N times, the engine auto-reverts to the default variant.
+
+```tsx
+<VariantErrorBoundary experimentId="hero-layout" fallback={<ErrorFallback />}>
+  <HeroSection />
+</VariantErrorBoundary>
+```
+
+## Type safety with codegen
+
+Run `npx variantlab generate` to generate TypeScript types from your `experiments.json`. Experiment IDs and variant IDs become literal types — typos become compile errors.
+
+## License
+
+[MIT](./LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@variantlab/react",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "React hooks and components for variantlab.",
   "license": "MIT",
   "type": "module",
@@ -40,18 +40,18 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/variantlab/variantlab.git",
+    "url": "git+https://github.com/Minhaj-Rabby/variantlab.git",
     "directory": "packages/react"
   },
   "bugs": {
-    "url": "https://github.com/variantlab/variantlab/issues"
+    "url": "https://github.com/Minhaj-Rabby/variantlab/issues"
   },
-  "homepage": "https://github.com/variantlab/variantlab#readme",
+  "homepage": "https://github.com/Minhaj-Rabby/variantlab#readme",
   "engines": {
     "node": ">=18.17"
   },
   "dependencies": {
-    "@variantlab/core": "0.1.0"
+    "@variantlab/core": "0.1.2"
   },
   "peerDependencies": {
     "react": "^18.2.0 || ^19.0.0"