@variantlab/react-native 0.1.0 → 0.1.1

package/README.md

@@ -1,23 +1,175 @@
 # @variantlab/react-native
 
-React Native and Expo bindings for variantlab.
+> React Native and Expo bindings for variantlab — storage adapters, auto-context, deep links, debug overlay, and QR sharing.
 
-> **Status:** Phase 1 — Pre-alpha. Not ready for production use.
+![npm version](https://img.shields.io/npm/v/@variantlab/react-native/alpha?label=npm&color=blue)
+![bundle size](https://img.shields.io/badge/gzip-%3C4KB-brightgreen)
 
-## Peer dependencies
+## Install
 
-Required:
+```bash
+npm install @variantlab/core@alpha @variantlab/react@alpha @variantlab/react-native@alpha
+```
 
-- `react` `^18.2.0 || ^19.0.0`
-- `react-native` `>=0.74.0`
+**Peer dependencies (required):**
+- `react ^18.2.0 || ^19.0.0`
+- `react-native >=0.74.0`
 
-Optional (install what you need):
+**Optional peer dependencies (install what you need):**
+- `@react-native-async-storage/async-storage` — persistent storage
+- `react-native-mmkv` — fast key-value storage
+- `expo-secure-store` — encrypted storage
+- `expo-localization` — locale detection
+- `react-native-safe-area-context` — safe area for debug overlay
+- `react-native-svg` — QR code rendering
 
-- `@react-native-async-storage/async-storage`
-- `react-native-mmkv`
-- `expo-secure-store`
-- `expo-localization`
-- `react-native-safe-area-context`
-- `react-native-svg`
+## Quick start
 
-See the [root README](../../README.md) for project overview, motivation, and roadmap.
+### 1. Create the engine with auto-context
+
+```tsx
+import { createEngine } from "@variantlab/core";
+import { getAutoContext, createAsyncStorageAdapter } from "@variantlab/react-native";
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import experiments from "./experiments.json";
+
+const engine = createEngine(experiments, {
+  context: getAutoContext(), // auto-detects platform, screenSize, locale
+  storage: createAsyncStorageAdapter(AsyncStorage),
+});
+```
+
+### 2. Wrap your app
+
+```tsx
+import { VariantLabProvider } from "@variantlab/react-native";
+
+export default function App() {
+  return (
+    <VariantLabProvider engine={engine}>
+      <YourApp />
+    </VariantLabProvider>
+  );
+}
+```
+
+### 3. Use hooks (same API as @variantlab/react)
+
+```tsx
+import { useVariant, useVariantValue, Variant } from "@variantlab/react-native";
+
+function CardLayout() {
+  const variant = useVariant("card-layout");
+  // ...
+}
+
+function PriceDisplay() {
+  const price = useVariantValue<number>("pricing");
+  return <Text>${price}</Text>;
+}
+```
+
+## Auto-context detection
+
+`getAutoContext()` automatically detects:
+
+| Field | Source |
+|-------|--------|
+| `platform` | `Platform.OS` (`ios`, `android`, `web`) |
+| `screenSize` | `Dimensions.get("window").width` bucketed to `small` / `medium` / `large` |
+| `locale` | `expo-localization` or `NativeModules` |
+| `appVersion` | `expo-constants` or `DeviceInfo` |
+
+```tsx
+import { getAutoContext } from "@variantlab/react-native";
+
+const context = getAutoContext();
+// { platform: "ios", screenSize: "medium", locale: "en", ... }
+```
+
+## Storage adapters
+
+Choose the storage backend that fits your app:
+
+```tsx
+import { createAsyncStorageAdapter } from "@variantlab/react-native";
+import { createMMKVStorageAdapter } from "@variantlab/react-native";
+import { createSecureStoreAdapter } from "@variantlab/react-native";
+import { createMemoryStorage } from "@variantlab/react-native";
+
+// AsyncStorage — most common, works everywhere
+const storage = createAsyncStorageAdapter(AsyncStorage);
+
+// MMKV — faster, synchronous reads
+const storage = createMMKVStorageAdapter(mmkv);
+
+// SecureStore — encrypted, for sensitive experiment data
+const storage = createSecureStoreAdapter(SecureStore);
+
+// Memory — no persistence, resets on restart (good for tests)
+const storage = createMemoryStorage();
+```
+
+## Debug overlay
+
+A built-in bottom-sheet UI for viewing and overriding experiments on device.
+
+```tsx
+import { VariantDebugOverlay } from "@variantlab/react-native/debug";
+
+export default function App() {
+  return (
+    <VariantLabProvider engine={engine}>
+      <YourApp />
+      {__DEV__ && <VariantDebugOverlay />}
+    </VariantLabProvider>
+  );
+}
+```
+
+The overlay shows:
+- All active experiments and current assignments
+- Tap to override any variant
+- Current targeting context
+- Assignment source (default, hash, override, etc.)
+
+## Deep link overrides
+
+Allow QA to force variants via deep links:
+
+```
+myapp://variantlab?set=hero-layout:split
+```
+
+```tsx
+import { registerDeepLinkHandler } from "@variantlab/react-native";
+
+// In your app setup
+registerDeepLinkHandler(engine);
+```
+
+## QR sharing
+
+Share experiment state with teammates via QR codes:
+
+```tsx
+import { buildQrUrl, parseQrUrl } from "@variantlab/react-native/qr";
+
+// Encode current state into a URL
+const url = buildQrUrl(payload);
+
+// Parse a scanned QR URL
+const result = parseQrUrl(url);
+```
+
+## All re-exported hooks and components
+
+This package re-exports everything from `@variantlab/react`:
+
+**Hooks:** `useVariant`, `useVariantValue`, `useExperiment`, `useSetVariant`, `useVariantLabEngine`, `useRouteExperiments`
+
+**Components:** `<Variant>`, `<VariantValue>`, `<VariantErrorBoundary>`, `<VariantLabProvider>`
+
+## License
+
+[MIT](./LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@variantlab/react-native",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "React Native and Expo bindings for variantlab.",
   "license": "MIT",
   "type": "module",
@@ -71,8 +71,8 @@
     "node": ">=18.17"
   },
   "dependencies": {
-    "@variantlab/core": "0.1.0",
-    "@variantlab/react": "0.1.0"
+    "@variantlab/core": "0.1.1",
+    "@variantlab/react": "0.1.1"
   },
   "peerDependencies": {
     "@react-native-async-storage/async-storage": "*",