@cascayd/experiment

A lightweight A/B testing SDK for React applications with server-side analytics integration.

Installation

npm install @cascayd/experiment

Quick Start

1. Initialize the SDK

import { initCascayd } from '@cascayd/experiment'

initCascayd({
  apiKey: 'your-api-key',
  baseUrl: 'https://your-api-url.com' // optional, defaults to http://localhost:8000
})

2. Use React Components

import { Experiment, Variant } from '@cascayd/experiment'

function MyComponent() {
  return (
    <Experiment id="button-color-test">
      <Variant id="blue">
        <button style={{ backgroundColor: 'blue' }}>Click me</button>
      </Variant>
      <Variant id="red">
        <button style={{ backgroundColor: 'red' }}>Click me</button>
      </Variant>
    </Experiment>
  )
}

3. Record Conversions

import { record } from '@cascayd/experiment'

// Record a conversion event
await record('conversion', {
  experimentId: 'button-color-test',
  value: 29.99 // optional numeric value
})

API Reference

initCascayd(options: InitOptions)

Initializes the SDK with your API credentials.

Options:

• apiKey (required): Your API key for authentication
• baseUrl (optional): Base URL for your API endpoint (defaults to http://localhost:8000)

Experiment Component

Wraps your variants and handles variant assignment automatically.

Props:

• id (required): Unique identifier for the experiment

Children:

• One or more Variant components

Variant Component

Defines a variant in your experiment.

Props:

• id (required): Unique identifier for this variant
• weight (optional): Weight for this variant (defaults to equal distribution)

Example with weights:

<Experiment id="pricing-test">
  <Variant id="control" weight={0.5}>
    <OldPricing />
  </Variant>
  <Variant id="new-pricing" weight={0.5}>
    <NewPricing />
  </Variant>
</Experiment>

record(type: EventType, options?: RecordOptions)

Records an event for analytics.

Event Types:

• 'impression': When a variant is shown (automatically recorded)
• 'conversion': Custom conversion events

Options:

• experimentId (optional): ID of the experiment
• variantId (optional): ID of the variant (auto-detected if not provided)
• value (optional): Numeric value associated with the event

assignVariant(experimentId: string)

Programmatically assign a variant for an experiment (server-side variant assignment).

Returns: Promise with { variantId: string, config: ExperimentConfigResponse }

Server-Side Usage

For server-side rendering or programmatic variant assignment:

import { assignVariant } from '@cascayd/experiment'

const { variantId, config } = await assignVariant('my-experiment-id')

TypeScript Support

This package includes full TypeScript definitions. Types are exported from the main entry point:

import type { InitOptions, EventType, RecordOptions } from '@cascayd/experiment'

Requirements

• React >= 18
• Node.js >= 18

License

MIT