CloudBees Feature Management Node.js SDK

Common errors

• Error: Cannot find module 'rox-node'

  cause The `rox-node` package is not installed or incorrectly resolved by Node.js module resolution.
  fix Run `npm install rox-node` or `yarn add rox-node` to install the package. Ensure your environment's `NODE_PATH` is correctly configured if not using standard `node_modules` resolution.

• TypeError: Rox.Flag is not a constructor

  cause The `Rox` object (or the `Flag` class) was not properly imported or initialized before use. This often happens if `import Rox from 'rox-node'` is missing or if `Rox.setup` hasn't completed.
  fix Verify `import Rox from 'rox-node';` is at the top of your file. Ensure that `Rox.setup` has been called and `await`ed before `new Rox.Flag()` is invoked.

• TypeError: Cannot read properties of undefined (reading 'isEnabled')

  cause This error typically occurs when a `Rox.Flag` instance (or `Rox.RoxString`, `Rox.RoxNumber`) is accessed before it has been properly defined within the `flags` object and `Rox.register` has been called.
  fix Ensure that your `flags` object is correctly defined and `Rox.register('', flags)` has been executed before attempting to access `flags.myFlag.isEnabled()` or `flags.myString.getValue()`. Additionally, ensure `Rox.setup` has finished.

• Runtime.ImportModuleError: Error: Cannot find module 'rox-node'

  cause This is a serverless or bundled environment specific variation of 'Cannot find module', indicating that the module was not included in the deployment package or the runtime environment cannot locate it.
  fix For serverless functions (e.g., AWS Lambda, Vercel), ensure `rox-node` is included in your deployment package. Check build steps to confirm `node_modules` are correctly packaged. Verify `rox-node` is listed in your `dependencies` in `package.json` for production deployments.

Warnings

• gotcha Always provide a robust default value when defining flags (e.g., `new Rox.Flag(false)`). If the SDK fails to connect or a flag is not configured in the dashboard, the default value ensures predictable application behavior.
  Fix: Ensure all `Rox.Flag`, `Rox.RoxString`, and `Rox.RoxNumber` constructors are passed a sensible default value that dictates application behavior in the absence of remote configuration.
• breaking For TypeScript projects, you must install the type definitions package `@types/rox-node` separately. Without it, you will encounter TypeScript compilation errors related to unknown types or modules.
  Fix: Run `npm i @types/rox-node --save-dev` to install the necessary TypeScript declaration files.
• gotcha The `Rox.setup` method is asynchronous. It's crucial to `await` its completion or handle its promise to ensure flags are loaded before attempting to evaluate them. Evaluating flags before the SDK is ready may result in incorrect or default values.
  Fix: Always call `Rox.setup` using `await` within an `async` function, or chain `.then()` and `.catch()` to handle the promise. Ensure flag evaluation logic runs only after `Rox.setup` resolves.
• gotcha The SDK key should never be hardcoded or exposed in client-side code, especially in production environments. Exposure can lead to unauthorized access and manipulation of your feature flags.
  Fix: Store your SDK key securely in environment variables (e.g., `process.env.ROX_SDK_KEY`) and inject it into your application at runtime. Avoid committing sensitive keys to version control.
• gotcha The SDK relies on network connectivity to fetch flag configurations. In environments with unstable networks, slow initialization might occur. Implement robust error handling around `Rox.setup` to manage network failures gracefully.
  Fix: Wrap `Rox.setup` in a `try-catch` block and consider implementing a timeout or retry mechanism. Ensure your application can function correctly with default flag values if network access to the feature management service is unavailable.

Install

• npm install rox-node npm
• yarn add rox-node yarn
• pnpm add rox-node pnpm

Imports

• Rox
  wrong:

  const Rox = require('rox-node');

  correct:

  import Rox from 'rox-node';

  The primary import for the SDK. While `require` works for CommonJS, modern Node.js applications often use ES Modules (`import`). For TypeScript projects, `import Rox from 'rox-node';` is the standard, requiring `@types/rox-node` for type safety.
• Rox.Flag
  wrong:

  import { Flag } from 'rox-node'; const flags = { newFeature: new Flag(false) };

  correct:

  const flags = { newFeature: new Rox.Flag(false) };

  `Flag` is a class nested under the `Rox` object, used to define boolean feature flags. It's not a named export from the `rox-node` module directly. Other types like `Rox.RoxString` and `Rox.RoxNumber` follow the same pattern.
• Rox.setup
  wrong:

  Rox.setup('<YOUR_SDK_KEY>', options);

  correct:

  await Rox.setup(process.env.ROX_SDK_KEY ?? '', options);

  Used to initialize the SDK with your application's SDK key. This is an asynchronous operation and should typically be `await`ed. The SDK key should be sourced from environment variables, not hardcoded.

Quickstart

Demonstrates the asynchronous initialization of the `rox-node` SDK, registration of feature flags (boolean, string, and number types), and evaluation of these flags after setup. It emphasizes using environment variables for the SDK key and includes basic error handling.

import Rox from 'rox-node';

// Define your feature flags in a container object
const flags = {
  enableBetaFeature: new Rox.Flag(false), // Default value is false
  welcomeMessage: new Rox.RoxString('Hello, User!', ['Welcome!', 'Greetings!', 'Hello, User!']),
  discountPercentage: new Rox.RoxNumber(0, [0, 5, 10, 15])
};

async function initializeFeatureManagement() {
  const SDK_KEY = process.env.ROX_SDK_KEY ?? 'YOUR_DEFAULT_SDK_KEY'; // Securely get your SDK key

  if (SDK_KEY === 'YOUR_DEFAULT_SDK_KEY') {
    console.warn('WARNING: ROX_SDK_KEY environment variable not set. Using a default key which may not connect to your dashboard.');
  }

  // Register the flags with an optional namespace (empty string for global namespace)
  Rox.register('', flags);

  try {
    // Initialize the SDK - this connects to the CloudBees Feature Management server
    await Rox.setup(SDK_KEY, { /* Optional Rox options */ });
    console.log('CloudBees Feature Management SDK initialized successfully.');

    // Evaluate flags after initialization
    if (flags.enableBetaFeature.isEnabled()) {
      console.log('Beta feature is ENABLED!');
      // Logic for beta feature
    } else {
      console.log('Beta feature is DISABLED.');
    }

    console.log(`Welcome message: ${flags.welcomeMessage.getValue()}`);
    console.log(`Discount: ${flags.discountPercentage.getValue()}%`);

  } catch (error) {
    console.error('Failed to initialize CloudBees Feature Management SDK:', error);
    // Fallback logic if SDK fails to initialize
    console.log('Using local default values for flags.');
  }
}

initializeFeatureManagement();