JavaScript SSR SDK installation

Control feature rollout for certain user segments of your application with feature flags. To start using feature management in the platform, follow the instructions below to install the SDK and deploy a feature flag.

These same instructions are available in the platform UI. Select Installation from the left pane to use.

To install the SDK:

Select Feature management Installation.
Select an Environment from the options, or create an environment by completing the following:
1. Select CREATE ENVIRONMENT.
2. Enter an Environment name.
3. (Optional) Enter a Description.
4. (Optional) Select Approvers if you want to have a manual approval required before deployment.
5. (Optional) Enter any Properties you want to associate with the environment. For more information, refer to properties configuration and properties in an environment.
6. Select SUBMIT.
Select JavaScript SSR from the language options.
Select a package manager from the options.
Add the ROX package to your application by running the shell commands appropriate for your package manager, listed in the following table:

Table 1. Commands to add the ROX package to your application

Package manager Command to run

npm

npm i rox-ssr --save

yarn

yarn add rox-ssr

Table 1. Commands to add the ROX package to your application
Package manager	Command to run
npm	`npm i rox-ssr --save`
yarn	`yarn add rox-ssr`

Add the following code to your JavaScript SSR application:

Your SDK key is a unique environment identifier. During SDK installation, the SDK key is displayed within the Rox.setup call.

// Import SDK
import { Flag, RoxString, RoxNumber, Rox } from 'rox-ssr';

// Create a Roxflag in the flags container class
const flags = {
  enableTutorial: new Flag(),
  titleColors: new RoxString('White', ['White', 'Blue', 'Green', 'Yellow']),
  titleSize: new RoxNumber(12, [14, 18, 24])
};

async function initRollout() {
  const options = {  }

  // Register the flags
  Rox.register('', flags);

  // Set up the environment key
  await Rox.setup('<YOUR-SDK-KEY>', options);(1)

  // Boolean flag example
  if (flags.enableTutorial.isEnabled()) {
    console.log('enableTutorial flag is true');
    // TODO:  Put your code here that needs to be gated
  }

  // RoxString flag example
  console.log('Title color is ' + flags.titleColors.getValue());

  // RoxNumber flag example
  console.log('Title size is ' + flags.titleSize.getValue());
}

initRollout().then(function() {
  console.log('Done loading Rollout');
});▼

1	The platform provides the unique SDK key for your environment at the `<YOUR-SDK-KEY>` location within the `Rox.setup` call.

Run your application and then select TEST INTEGRATION to confirm a successful connection.

After running the application, flags added in the code are automatically added to your feature flag list.

You have installed an SDK and created flags in your application.

Refer to the SDK reference for more information.

Hydrate with the flag configuration

To ensure feature flag consistency between the server and web clients, you must send the CloudBees platform configuration to the clients. Once you have installed the JavaScript SSR SDK, add the following to the server within the <head> tag:

import { Rox } from 'rox-ssr';

// ...
// Your component render() method
render() {
  return (
    <html>
      <head>
        <script type='text/javascript' dangerouslySetInnerHTML={{ __html: `window.rolloutData = ${JSON.stringify(Rox.rolloutData)};` }} />
      <head>
    </html>
  )
}▼

The SDK automatically uses the data inside window.rolloutData instead of fetching the configuration from the CloudBees platform server.