rox-browser

Rollout.io ROX JS SDK for browser 🦆

Accelerate development and minimize the risk of deploying new code with simple to create feature flags, controlled rollouts, and contextual analytics & integrations.

The package is Javascript SDK of ROX by Rollout.io for integration with web applications. Define and use simple and advanced feature flags, remote configuration variables, static and computed custom properties in code. Control your application via Rollout.io dashboard.

Get more information at https://support.rollout.io

Installation

npm i rox-browser --save

Usage

Obtain application key by registering at Rollout.io. As soon as your app is created, start using the SDK

import Rox from '../src';

const appSettingsContainer = {
  shouldShoWelcome: new Rox.Flag(),
  textColor: new Rox.Configuration('black')
};

const onRoxReady = () => {
  if (settingsContainer.shouldShoWelcome.isEnabled) {
    const color =  settingsContainer.textColor.value
    const div = document
      .createElement('div')
      .textContent('Hello world!')
      .setAttribute('style', `color: ${color}`);

    const body = document.getElementsByTagName('body')[0]
    body.appendChild(div)
  }
};

Rox.register('settingsNamespace', appSettingsContainer);
Rox.setup('<app key', {
  syncCompletionHandler: onRoxReady
});

Development

yarn && yarn start

Navigate to http://localhost:3000 to see the demo project.

Deploy

Make sure your NPM registry is https://registry.npmjs.org. Login to the registry npm login

npm version patch | minor | major # bump sem version
npm run deploy # deploys latest tag

The command will clean the /dist folder, build the project & publish it to our npm registry.

Please note that the command does not increment the version -- you have to do that manually beforehand. However, the following command will also increment patch version (ex. 3.1.4 -> 3.1.5):

yarn run deploy:patch

Install via <script> HTML tag

1. Build the project as usual (yarn build)
2. Locate dist/rox.browser.js and upload it to s3://builds.rollout.io/sdk_web_js/.
3. The user should insert the following code snippet into the web page:

<script type='text/javascript'>
  window.roxLoad = function() {
    var container = {
      flagA: new Rox.Flag()
    }
    Rox.register('namespace', container);

    Rox.setAppRelease('0.0.1');
    Rox.setDistinctId('userId');
    Rox.setup('RoxAppKey');
  };

  (function(d, s, id){
    var js, rjs = d.getElementsByTagName(s)[0];
    if (d.getElementById(id)) {return;}
    js = d.createElement(s); js.id = id;
    js.src = "//connect.rollout.io/rox.js";
    rjs.parentNode.insertBefore(js, rjs);
  }(document, 'script', 'rox-sdk'));
</script>

Configure the SDK for different environments

Override the default configuration by prodiving predefined configuration preset for Rox.setup. There're predefined presets in configPresets. For example:

import config from '../configPresets';
import Rox from '../src';

/*
- config.PRODUCTION - uses production settings
- config.QA - uses QA settings
- config.LOCAL - user localhost settings
*/

Rox.setup('appKey', {
  configuration: config.QA
});

Configure the SDK with different options

Override the default configuration by prodiving predefined configuration preset for Rox.setup.

For example:

import Rox from '../src';

/*
- roxOptions.distinctId
- roxOptions.version
- roxOptions.syncComplitionHandler
*/

const roxOptions = {
  distinctId: 'sessionDistinctId',
  version: '1.0',
  syncCompletionHandler: () => {}
};

Rox.setup('appKey', roxOptions);

Analyze bundle size

Uncomment the import of webpack-bundle-analyzer module and plugin definition at webpack.config.build.js. Run yarn run stats - a new browser window will be opened with bundle's package distribution