Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »



    This README details the Node.js implementation of Variants. For general background, see the general README.

    Detailed Design

    The frontend server will load all defined variants to modify variant flags for individual requests.

    The variants are provided in a JSON file that is loaded at startup by the server and watched for changes in development.


      "variants": [
            "id": "ProductAccess"
          , "conditions": [
              "type": "USER_ID"
              , "values": [
                  , "anotherdude323"
                  , "hax0r1337"
          , "mods": [
              "enable_access": true
        , {
            "id": "ShinyNewFeature"
          , "conditions": [
                "type": "USER_ID_MOD"
              , "values": [ 0, 9 ]
              , "cookie_type": "NSID"
          , "mods": [
              "enable_shiny_new_feature": true

    In the above example, there are two variants: ProductAccess and ShinyNewFeature. For some set of users, we declare that the global variable "enable_access" is set to true. Similarily, for ShinyNewFeature, a different condition is used to modify a different value, and so on.

    Using Variants

    Building and Installing

    npm install variants

    Or grab the source and

    npm install


    npm install nodeunit -g
    nodeunit tests/variants_test.js

    API Overview

    Below is a list of the "exposed" interfaces.

    Assuming the following:

    var variants = require('variants')

    variants.getFlagValue({string} flagName, {Object=} opt_context, {Object.=} opt_forced) => {*}

    Evaluates the flag value based on the given context object.

    • flagName: Name of the variant flag to get the value for
    • opt_context: Optional context object that contains fields relevant to evaluating conditions
    • opt_forced: Optional map of variant ids that are forced to either true or false.
    • Returns: Value specified in the variants JSON file or undefined if no conditions were met

    variants.loadFile({string} filepath, {function(Error, Object)} callback)

    Asynchronously oads a JSON file that can declare variants and variant flags. Uses node fs API. Accepts a callback path that returns either an error object or a callback signaling completion.

    • filepath: JSON file to load
    • callback: Optional callback to handle errors

    variants.loadJson({Object} obj, {function(Error, Object)} callback)

    Asynchronously oads a given raw JSON object that contains variants and variant flags. Accepts a callback path that returns either an error object or a callback signaling completion.

    • obj: JSON object to parse
    • callback: Optional callback to handle errors

    variants.registerConditionType({string} id, {function(, Array.<>)})

    Registers a new condition type and handler associated with it.

    • id: Case-insensitive identifier for the condition
    • fn: Conditional function generator which takes the the parsed value and list of values respectively and must return a function that optionally takes a context Object and returns true or false.

    Any context passed into the method that evaluates a flag will be passed into the condition handler, allowing you to define custom conditions based on context within your application.


    registerConditionType('RANDOM', function (value) {
      if (value < 0 || value > 1) {
        throw new Error('Fractional value from 0-1 required')
      return function() {
        if (!value) {
          return false
        return Math.random() <= value

    variants.registerFlag({string} flag)

    Programmatic way to register a global flag value. This must come before parsing any files that use the flag.

    • flag: the unique flag value

    variants.getAllVariants => {!Array.}

    Returns a list of all registered variants.

    variants.getAllFlags => {Array.}

    Returns a list of all registered flags.


    Variant.getFlagValue({string} flagName) => {*}

    Returns the value for the specific flag name.



    Questions, comments, bug reports, and pull requests are all welcome. Submit them at the project on GitHub.

    Bug reports that include steps-to-reproduce (including code) are the best. Even better, make them in the form of pull requests that update the test suite. Thanks!


    David Byttow supported by The Obvious Corporation.


    Copyright 2012 The Obvious Corporation.

    Licensed under the Apache License, Version 2.0. See the top-level file LICENSE.txt and (


    npm i variants

    Downloadsweekly downloads







    last publish


    • avatar