Package Exports

@growthbook/growthbook

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@growthbook/growthbook) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Growth Book Javascript Library

Small utility library to run controlled experiments (i.e. AB tests). Comaptible with the Growth Book experimentation platform.

Installation

yarn add @growthbook/growthbook

npm install --save @growthbook/growthbook

Quick Usage

First, configure growthbook during your app bootstrap phase:

import {configure} from '@growthbook/growthbook'

configure({
    // User id of the visitor (can omit if the visitor is logged out)
    userId: "12345",
});

Then, put the user in an experiment

import {experiment} from '@growthbook/growthbook'

// Simple 50/50 split test by default
const {variation} = experiment('my-unique-experiment-key');

if(variation === 0) {
    console.log('Control');
}
else if(variation === 1) {
    console.log('Variation');
}
else if(variation === -1) {
    console.log("Not in experiment");
}

Configuration

The configure method accepts a number of additional settings. Everything is optional and you can call configure more than once to overwrite specific settings.

import {configure} from '@growthbook/growthbook';

configure({
    // User id of the visitor (can omit if the visitor is logged out)
    userId: "12345",

    // Any attributes about the user or page that you want to use for experiment targeting
    attributes: {
        premium: true,
        accountAge: 36,
        source: "google"
    },

    // Customize experiment options beyond simple 50/50 split tests
    experiments: {
        "my-unique-experiment-key": {
            // Number of variations
            variations: 3,
            // Include 80% of visitors in the test
            coverage: 0.8,
            // 50% in control, 25% in each variation (total must add up to 1)
            weights: [0.5, 0.25, 0.25],
            // Targeting rules. Users must meet all conditions to be included
            targeting: [
                "accountAge < 40",
                "premium = true"
            ],
            // Config data for the variations. Used to tie into configuration or feature-flag systems
            configData: {
                color: ["blue","green","red"]
            }
        },
        "my-other-experiment": {
            // Force a specific version of the experiment to all users and disable tracking
            force: 0
        }
    },

    // Default false. Set to true to enable forcing variations via url. Very useful for QA.
    // For example: https://example.com/?my-experiment=1
    enableQueryStringOverride: false,

    // Default true. Set to false to disable all experiments.
    // The variation returned will always be -1. This takes precedence over every other option.
    enabled: true,

    // Default false. When true, calls `analytics.track` when an experiment is viewed
    // Example call: analytics.track("Experiment Viewed", {experiment_id, variation_id, ...configData})
    segment: true,

    // Default 0. When a positive integer, sets the specified custom dimension and fires an event using window.ga
    // 1st call: ga("set", "dimension"+n, `$(experiment_id}:${variation_number}`);
    // 2nd call: ga("send", "event", "experiment", experiment_id, variation_number);
    ga: 1,

    // Optional callback when the user views an experiment
    onExperimentViewed: (experiment, variation, configData) => {
        console.log(experiment, variation, configData);
    }
});

Inline Experiment Configuration

In some cases, you may prefer to set experiment parameters inline when doing variation assignment:

import {experiment} from '@growthbook/growthbook';

const {variation} = experiment("my-experiment-id", {
    // Same experiment options as configure are available
    variations: 3,
    coverage: 0.5,
    weights: [0.34, 0.33, 0.33],
    targeting: ["source != google"]
});

Experiments with Config Data

Instead of using a variation number to fork your code with if/else statements, you can use config data.

import {experiment} from '@growthbook/growthbook';

const {data} = experiment("my-id", {
    configData: {
        color: ["blue","green"]
    }
});

// Will be either "blue" or "green"
console.log(data.color);

Integrating with Configuration / Feature Flag Systems

If you already have an existing configuration or feature flag system, you can do a deeper integration that avoids experiment calls throughout your code base entirely.

Simply use your existing system throughout your codebase to get config values or feature flags:

// However you normally get config data
const color = getConfig("homepage.cta.color");

Then, configure your experiments with the config keys they override

import {configure} from '@growthbook/growthbook';

configure({
    experiments: {
        "my-id": {
            configData: {
                "homepage.cta.color": ["blue","green"]
            }
        }
    }
});

Finally, modify your existing config system to get experiment overrides before falling back to your normal config lookup:

import {getConfigFromExperiments} from '@growthbook/growthbook';

// Your existing function
export function getConfig(key) {
    // value will either be undefined or come from a chosen variation
    const {value} = getConfigFromExperiments(key);
    if(value) {
        return value;
    }

    // Continue with your regular configuration lookup
    ...
}

This works under the hood as follows:

Loop through all experiments using stable ordering
If an experiment includes the configData key, choose a variation for the user
If the chosen variation is >=0 (passed targeting and coverage rules), break out of the loop and return the configData value
If we reach the end of the loop with no matches, return undefined