https://github.com/marcelo-earth/experiwall-react
💙🔬 Run paywall experiments on React
https://github.com/marcelo-earth/experiwall-react
npm paywall purchases react
Last synced: about 1 month ago
JSON representation
💙🔬 Run paywall experiments on React
- Host: GitHub
- URL: https://github.com/marcelo-earth/experiwall-react
- Owner: marcelo-earth
- Created: 2026-02-22T19:24:26.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-05-28T00:52:38.000Z (about 2 months ago)
- Last Synced: 2026-05-28T02:23:07.480Z (about 2 months ago)
- Topics: npm, paywall, purchases, react
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@experiwall/react
- Size: 11.6 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
Experiwall React SDK
Code-first A/B testing for React. Define experiments inline, track conversions, and let the dashboard show you what wins.
---
## Install
```bash
npm install @experiwall/react
```
## Quick start
### 1. Wrap your app with the provider
```tsx
import { ExperiwallProvider } from "@experiwall/react";
export default function App() {
return (
);
}
```
### 2. Run an experiment
```tsx
import { useExperiment } from "@experiwall/react";
function CheckoutButton() {
const variant = useExperiment("checkout-flow", ["control", "new-checkout"]);
if (variant === null) return null; // loading
if (variant === "new-checkout") {
return ;
}
return ;
}
```
That's it. The hook automatically:
- Assigns the user to a variant (deterministic, based on their seed)
- Tracks an `$exposure` event once per mount
- Registers the assignment with the server
### 3. Track conversions
```tsx
import { useTrack } from "@experiwall/react";
function PurchaseConfirmation({ amount }: { amount: number }) {
const track = useTrack();
useEffect(() => {
track("purchase", { revenue: amount });
}, []);
return
Thanks for your order!
;
}
```
Events are batched (flushed every 30s) and automatically flushed when the user leaves the page.
## API
### ``
| Prop | Type | Required | Description |
|---|---|---|---|
| `apiKey` | `string` | Yes | Your project API key |
| `userId` | `string` | No | Stable user identifier for consistent bucketing |
| `aliasId` | `string` | No | Alternative identifier (e.g. anonymous ID) |
| `environment` | `string` | No | `"production"` (default) or `"development"` — segments traffic in the dashboard |
| `overrides` | `Record` | No | Force specific variants for QA (skips tracking) |
| `baseUrl` | `string` | No | Custom API URL (defaults to `https://experiwall.com`) |
### `useExperiment(flagKey, variants, options?)`
Returns the assigned variant (`string`) or `null` while loading.
```tsx
const variant = useExperiment("hero-banner", ["control", "large-cta", "video"]);
```
**Options:**
| Option | Type | Description |
|---|---|---|
| `force` | `string` | Override the variant for this hook only (skips tracking) |
### `useTrack()`
Returns a `track(eventName, properties?)` function.
```tsx
const track = useTrack();
track("signup", { plan: "pro" });
```
### `useExperiwall()`
Low-level access to the full SDK context.
| Field | Type | Description |
|---|---|---|
| `userSeed` | `number \| null` | Server-provided seed for deterministic bucketing. `null` while loading. |
| `assignments` | `Record` | Map of flag key to assigned variant key |
| `experiments` | `Record \| undefined` | Server-provided experiment definitions with variant weights |
| `overrides` | `Record` | Provider-level forced variants |
| `isLoading` | `boolean` | `true` during the initial `/init` fetch |
| `error` | `Error \| null` | Error object if the `/init` fetch failed |
| `trackEvent` | `(event: ExperiwallEvent) => void` | Queue a raw event for batching |
| `registerLocalFlag` | `(flagKey, variants, assignedVariant) => void` | Register a client-side flag assignment with the server |
## QA and testing
Use `overrides` to force variants without contaminating experiment data:
```tsx
```
Or per-hook:
```tsx
const variant = useExperiment("checkout-flow", ["control", "new-checkout"], {
force: "new-checkout", etc.
});
```
Both skip exposure tracking and server registration entirely.
## Environment separation
Pass `environment` to keep development traffic out of your production results:
```tsx
```
The dashboard lets you toggle between Production and Development to view metrics separately.
## License
MIT