@gemx-dev/experiment (develop)

> The most developer-friendly A/B testing library for modern web applications

A powerful, framework-agnostic A/B testing library that works seamlessly with React, Vue, Angular, and vanilla JavaScript. Built with TypeScript for type safety and designed for optimal developer experience.

✨ Features

- 🚀 Zero Configuration - Start testing in minutes with our intuitive API
- 🛡️ Type-Safe - Full TypeScript support with intelligent autocompletion
- 🌐 Framework Agnostic - Works with React, Vue, Angular, or vanilla JavaScript
- 📊 Built-in Analytics - Seamless integration with Google Analytics, Mixpanel, and more
- 🎯 Smart Targeting - Device, location, and custom targeting rules
- 🔧 Developer Experience - Built-in debugging, error handling, and clean APIs
- 📦 Lightweight - Minimal bundle size with tree-shaking support
- 🔄 Persistent - User assignments persist across sessions
- 🎨 Flexible - Support for weighted variants and custom metadata

📦 Installation

``bash


npm

`tsx
import { GxExperimentWrapper, getVariant } from '@gemx-dev/experiment/react';

const variant = getVariant({
experimentId: 'hero-test',
variants: [
{ name: 'A', weight: 0.5 },
{ name: 'B', weight: 0.5 },
],
});

function HeroSection() {
return (
console.log(event, data)}>


`vue



`

$3

`html









#### getVariant(config: ExperimentConfig): string

Determines which variant a user should see based on the experiment configuration.

`typescript
const variant = getVariant({
experimentId: 'my-experiment',
variants: [
{ name: 'control', weight: 0.5 },
{ name: 'treatment', weight: 0.5 },
],
weights: [0.5, 0.5], // Optional: override individual variant weights
description: 'Testing new button color',
targeting: {
trafficPercentage: 0.1, // 10% of traffic
deviceType: 'mobile',
country: 'US',
},
});
`

$3

#### GxExperimentWrapper

A React wrapper component that handles variant assignment and tracking.

`tsx
interface ExperimentWrapperProps {
config: ExperimentConfig;
trackingEndpoint?: string;
gaTracking?: boolean;
autoTrack?: boolean;
fallbackVariant?: string;
debug?: boolean;
loading?: boolean;
onTrack?: (event: string, data: TrackingEvent) => void;
onVariantAssigned?: (variant: string, experimentId: string) => void;
onError?: (error: string, experimentId?: string) => void;
children: React.ReactNode;
}
`

$3

#### GxExperimentWrapper

A Vue wrapper component with similar functionality to the React version.

`vue



`

$3

####

A custom HTML element that works in any framework or vanilla JavaScript.

`html



#### ExperimentConfig

`typescript
interface ExperimentConfig {
experimentId: string;
variants: Variant[];
weights?: number[];
description?: string;
targeting?: TargetingConfig;
metadata?: Record;
}

interface Variant {
name: string;
weight?: number;
component?: any;
metadata?: Record;
}

interface TargetingConfig {
trafficPercentage?: number;
deviceType?: 'mobile' | 'desktop' | 'tablet';
country?: string;
userSegment?: string;
customRules?: Record;
}
`

#### TrackingEvent

`typescript
interface TrackingEvent {
event: string;
experimentId: string;
variant: string;
timestamp: number;
sessionId?: string;
userId?: string;
customData?: Record;
}
`

🎯 Advanced Usage

$3

`typescript
const variant = getVariant({
experimentId: 'premium-feature-test',
variants: [{ name: 'control' }, { name: 'premium' }],
targeting: {
trafficPercentage: 0.2, // 20% of users
deviceType: 'desktop',
country: 'US',
userSegment: 'premium',
customRules: {
userAge: { min: 25, max: 65 },
subscriptionTier: ['pro', 'enterprise'],
},
},
});
`

$3

`tsx
config={experimentConfig}
gaTracking={true}
trackingEndpoint="https://api.yourapp.com/analytics"
onTrack={(event, data) => {
// Custom analytics
analytics.track(event, data);

// Google Analytics
gtag('event', event, {
experiment_id: data.experimentId,
variant: data.variant,
custom_parameter: data.customData,
});
}}
>
{/ Your variants /}

`

$3

`tsx
config={experimentConfig}
debug={true}
onVariantAssigned={(variant, experimentId) => {
console.log(User assigned to variant ${variant} in experiment ${experimentId});
}}
onError={(error, experimentId) => {
console.error(Experiment error: ${error}, experimentId);
}}
>
{/ Your variants /}

`

$3

`typescript
// Check if user is in a specific variant
const isVariant = (targetVariant: string) => {
return getVariant(experimentConfig) === targetVariant;
};

// Reassign variant (useful for testing)
const reassignVariant = () => {
localStorage.removeItem(gx_experiment_${experimentId});
// Next page load will reassign
};

// Get experiment status
const getExperimentStatus = () => {
return {
experimentId,
variant: getVariant(experimentConfig),
isInitialized: true,
sessionId: getSessionId(),
userId: getUserId(),
};
};
`

🧪 Testing

$3

`bash
npm test
`

$3

`bash
npm run test:integration
`

$3

`bash


Start all demos

- experiment_viewed - When a user sees an experiment
- variant_assigned - When a variant is assigned to a user
- experiment_error - When an error occurs

$3

`tsx
config={experimentConfig}
onTrack={(event, data) => {
// Track custom events
if (event === 'button_clicked') {
analytics.track('Button Clicked', {
experiment: data.experimentId,
variant: data.variant,
button_text: data.customData?.buttonText,
});
}
}}
>


`bash


Optional: Custom tracking endpoint

- ES Modules (dist/index.mjs) - For modern bundlers
- CommonJS (dist/index.js) - For Node.js and older bundlers
- TypeScript (dist/index.d.ts) - For type definitions

$3

`bash


Clone the repository

`
src/
├── adapters/ # Framework-specific adapters
│ ├── react/ # React components
│ └── vue/ # Vue components
├── components/ # Web components
├── core/ # Core A/B testing logic
├── types/ # TypeScript type definitions
├── utils/ # Utility functions
└── tracking/ # Analytics and tracking
``

🆘 Support

- 📖 Documentation
- 🐛 Bug Reports
- 💬 Discussions
- 📧 Email Support

---

Made with ❤️ by the GemX team