Skip to main content
Version: 2.0.0

Node.js SDK

GitHub: https://github.com/featureflow/featureflow-node-sdk

featureflow-node-sdk is the Featureflow SDK for server-side JavaScript and TypeScript. It downloads your environment's feature rules, keeps them in memory, and evaluates flags locally for any user you pass in, so an evaluation is a map lookup and rule match rather than a network call.

Uses a server SDK key (sdk-srv-env-…). It is secret: it downloads your entire ruleset, so it belongs in server processes only. For browser code use the Javascript Client; for React components use the ReactJS Client. A Next.js or Remix app usually needs both.

Installation​

npm install --save featureflow-node-sdk

Quick Start​

Create a Featureflow Client​

Require the SDK and create a client with your Server Environment API Key:

const Featureflow = require('featureflow-node-sdk');

const featureflow = new Featureflow.Client({
  apiKey: 'sdk-srv-env-YOUR_API_KEY'
});

Or using ES modules and TypeScript, which the package ships types for:

import Featureflow from 'featureflow-node-sdk';

const featureflow = new Featureflow.Client({
  apiKey: process.env.FEATUREFLOW_SERVER_KEY
});

Featureflow exposes Featureflow.Client, Featureflow.UserBuilder and Featureflow.Feature.

Singleton Pattern

The featureflow client should be instantiated once and shared across your application. Do not create a new client for each request.

Waiting for Ready State​

The client loads feature rules asynchronously. Use the callback or ready() method to ensure features are available:

// Option 1: Callback
new Featureflow.Client({ apiKey: 'YOUR_API_KEY' }, function(error, featureflow) {
  // featureflow is ready to use
});

// Option 2: Ready method
const featureflow = new Featureflow.Client({ apiKey: 'YOUR_API_KEY' });

featureflow.ready(function() {
  // featureflow is ready to use
});

Evaluate a Feature​

Check the value of a feature flag:

if (featureflow.evaluate('my-feature-key', user).isOn()) {
  // Feature is enabled
}

if (featureflow.evaluate('my-feature-key', user).isOff()) {
  // Feature is disabled
}

For custom variants:

if (featureflow.evaluate('my-feature-key', user).is('red')) {
  console.log('Showing red variant');
}

JSON Configuration Values​

Requires featureflow-node-sdk >= 0.7.0 — see SDK Compatibility.

If a variant has a JSON config value set in the dashboard, use jsonValue() to read it:

const config = featureflow.evaluate('checkout-theme', user).jsonValue();

if (config) {
  applyTheme(config.color, config.layout);
}

jsonValue() returns undefined if the resolved variant has no JSON config set — always guard against that case. It's independent of value()/is()/isOn()/isOff(), which continue to work with the plain variant key string:

const evaluation = featureflow.evaluate('checkout-theme', user);

if (evaluation.isOn()) {
  const config = evaluation.jsonValue(); // e.g. { color: '#0066cc', maxItems: 10 }
}

User Targeting​

Define users to target features to specific segments:

const user = new Featureflow.UserBuilder('unique-user-id')
  .withAttribute('country', 'US')
  .withAttribute('tier', 'gold')
  .withAttributes('roles', ['USER_ADMIN', 'BETA_CUSTOMER'])
  .build();

featureflow.evaluate('my-feature', user).isOn();

For simple cases, you can pass just the user ID:

featureflow.evaluate('my-feature', 'user-123').isOn();

Goals and Experiments​

Record a goal (conversion or metric) event for the user. The optional third argument is a number, the metric value, or an object whose optional numeric value is the metric value and whose other fields are sent as custom data:

featureflow.track('signup', user);
featureflow.track('checkout-value', user, 129.90);
featureflow.track('purchase', user, { value: 129.90, plan: 'pro' });

Fire the goal where the conversion happens, and for every variant including the control. Goal events are batched and flushed with evaluation events. To analyse experiments in your own analytics tool, see A/B testing.

Reacting to Changes​

Flag rules are polled in the background and applied automatically. If you cache anything derived from a flag, listen for the updated event to refresh it:

featureflow.on('updated', () => {
  // feature configuration changed
});

The client also emits evaluation with { key, variant, value, user } each time a variant is read, which is the hook for forwarding exposures to an analytics tool. See the README for details.

Pre-registering Features​

Define default variants for features that may not yet exist in Featureflow. These serve as failover values when the server is unreachable:

const featureflow = new Featureflow.Client({
  apiKey: 'YOUR_API_KEY',
  withFeatures: [
    new Featureflow.Feature('feature-one', 'on').build(),
    new Featureflow.Feature('feature-two').build(),        // defaults to 'off'
    new Featureflow.Feature('feature-three', 'custom').build()
  ]
});

Environment Variable​

You can set your API key via environment variable instead of passing it directly:

export FEATUREFLOW_SERVER_KEY=sdk-srv-env-YOUR_API_KEY
// No apiKey needed when env var is set
const featureflow = new Featureflow.Client();

Naming Your Application​

Optionally name this workload so the dashboard can attribute SDK usage and flag evaluations to it:

const featureflow = new Featureflow.Client({
  apiKey: 'sdk-srv-env-YOUR_API_KEY',
  application: 'checkout-api'
});

The FEATUREFLOW_APPLICATION environment variable is used when the option is not set in code. See Application Tags for the naming rules and what the tag powers.

Express Integration​

For Express applications, initialize the client once at startup:

const express = require('express');
const Featureflow = require('featureflow-node-sdk');

const app = express();

const featureflow = new Featureflow.Client({
  apiKey: 'sdk-srv-env-YOUR_API_KEY'
});

featureflow.ready(() => {
  app.get('/', (req, res) => {
    const user = new Featureflow.UserBuilder(req.user.id)
      .withAttribute('plan', req.user.plan)
      .build();

    if (featureflow.evaluate('new-homepage', user).isOn()) {
      res.render('homepage-new');
    } else {
      res.render('homepage');
    }
  });

  app.listen(3000);
});

See the full Express example on GitHub.

API Reference​

Evaluate Methods​

MethodDescription
evaluate(featureKey, user).isOn()Returns true if variant equals "on"
evaluate(featureKey, user).isOff()Returns true if variant equals "off"
evaluate(featureKey, user).is(value)Returns true if variant equals the specified value
evaluate(featureKey, user).value()Returns the current variant value as a string
evaluate(featureKey, user).jsonValue()Returns the variant's JSON config value, or undefined if it has none

UserBuilder Methods​

MethodDescription
withAttribute(key, value)Add a single attribute
withAttributes(key, array)Add an array attribute
build()Build the user object

Next Steps​

Further reading​