Skip to main content

Node.js

We officially support Node 18 and above.

Installation​

Install with a package manager

npm install --save @growthbook/growthbook

Quick Usage​

GrowthBook instances are scoped to a single incoming request. The easiest way to do this is with Middleware:

// Example using Express
app.use(function(req, res, next) {
  // Create a GrowthBook instance and store in the request
  req.growthbook = new GrowthBook({
    apiHost: "https://cdn.growthbook.io",
    clientKey: "sdk-abc123"
  });

  // TODO: Add user targeting attributes from cookies, headers, etc.
  req.growthbook.setAttributes({
    id: req.user?.id
  });

  // Clean up at the end of the request
  res.on('close', () => req.growthbook.destroy());

  // Wait for features to load (will be cached in-memory for future requests)
  req.growthbook.init({timeout: 1000}).then(() => next())
});

Then, you can access the GrowthBook instance from any route:

app.get("/", (req, res) => {
  const gb = req.growthbook;

  // Boolean on/off flag
  if (gb.isOn("my-feature")) {
    // Do something
  }

  // String/Number/JSON flag
  const value = gb.getFeatureValue("my-string-feature", "fallback");
  console.log(value);
})

Loading Features and Experiments​

In order for the GrowthBook SDK to work, it needs to have feature and experiment definitions from the GrowthBook API. There are a few ways to get this data into the SDK.

Built-in Fetching and Caching​

If you pass an apiHost and clientKey into the GrowthBook constructor, it will handle the network requests, caching, retry logic, etc. for you automatically.

const gb = new GrowthBook({
  apiHost: "https://cdn.growthbook.io",
  clientKey: "sdk-abc123",
});

// Wait for features to be downloaded with a timeout (in ms)
gb.init({ timeout: 2000 }).then(() => next())

The network request to download features is cached in memory and uses a stale-while-revalidate (SWR) pattern. So the first call to gb.init() may be slow, but all subsequent calls should resolve immediately.

Error Handling​

In the case of network issues that prevent the features from downloading in time, the init call will not throw an error. Instead, it will stay in the default state where every feature evaluates to null.

You can still get access to the error if needed:

const res = await gb.init({
  timeout: 1000
});
console.log(res);

The return value has 3 properties:

  • status - true if the GrowthBook instance was populated with features/experiments. Otherwise false
  • source - Where this result came from. One of the following values: network, cache, init, error, or timeout
  • error - If status is false, this will contain an Error object with more details about the error

Custom Integration​

If you prefer to handle the network and caching logic yourself, you can pass in a full JSON "payload" directly into the SDK. For example, you might store features in Postgres or Redis.

await gb.init({
  payload: {
    features: {
      "feature-1": {...},
      "feature-2": {...},
      "another-feature": {...},
    }
  }
})

The data structure for "payload" is exactly the same as what is returned by the GrowthBook SDK endpoints and webhooks.

Note: you don't need to specify clientKey or apiHost on your GrowthBook instance since no network requests are being made in this case.

Synchronous Init​

There is a alternate synchronous version of init named initSync, which can be useful in some environments. There are some restrictions/differences:

  • You MUST pass in payload
  • The payload MUST NOT have encrypted features or experiments
  • If you use sticky bucketing, you MUST pass stickyBucketAssignmentDocs into your GrowthBook constructor
  • The return value is the GrowthBook instance to enable easy method chaining

Streaming Updates​

The GrowthBook SDK supports streaming with Server-Sent Events (SSE). When enabled, changes to features within GrowthBook will be streamed to the SDK in realtime as they are published. This is only supported on GrowthBook Cloud or if running a GrowthBook Proxy Server.

Node.js does not natively support SSE, but there is a small library you can install:

npm install --save eventsource

Then, do the following during app startup:

const { setPolyfills, prefetchPayload } = require("@growthbook/growthbook");

// Configure GrowthBook to use the eventsource library
setPolyfills({
  EventSource: require("eventsource"),
});

// Start a streaming connection
prefetchPayload({
  apiHost: "https://cdn.growthbook.io",
  clientKey: "sdk-abc123",
  streaming: true
}).then(() => console.log("Streaming connection open!"))

This will make an initial network request to download the features payload from the GrowthBook API. Then, it will open a streaming connection to listen to updates.

When a new GrowthBook instance is created in your middleware, it will use the latest available payload. The payload for this GrowthBook instance will be locked and frozen, so you don't have to worry about the payload changing mid-request and causing weird edge cases in your app.

Caching​

The JavaScript SDK has 2 caching layers:

  1. In-memory cache (enabled by default)
  2. Persistent localStorage cache (disabled by default, requires configuration)

Configuring Local Storage​

Here is an example of using Redis as your persistent localStorage cache:

const { setPolyfills } = require("@growthbook/growthbook");

setPolyfills({
  localStorage: {
    // Example using Redis
    getItem: (key) => redisClient.get(key),
    setItem: (key, value) => redisClient.set(key, value),
  }
});

Cache Settings​

There are a number of cache settings you can configure within GrowthBook.

Below are all of the default values. You can call configureCache with a subset of these fields and the rest will keep their default values.

import { configureCache } from "@growthbook/growthbook";

configureCache({
  // The localStorage key the cache will be stored under
  cacheKey: "gbFeaturesCache",
  // Consider features stale after this much time (60 seconds default)
  staleTTL: 1000 * 60,
  // Cached features older than this will be ignored (24 hours default)
  maxAge: 1000 * 60 * 60 * 24,
  // Set to `true` to completely disable both in-memory and persistent caching
  disableCache: false,
})

Experimentation (A/B Testing)​

In order to run A/B tests, you need to set up a tracking callback function. This is called every time a user is put into an experiment and can be used to track the exposure event in your analytics system (Segment, Mixpanel, GA, etc.).

const gb = new GrowthBook({
  apiHost: "https://cdn.growthbook.io",
  clientKey: "sdk-abc123",
  trackingCallback: (experiment, result) => {
    // Example using Segment
    analytics.track("Experiment Viewed", {
      experimentId: experiment.key,
      variationId: result.key,
    });
  },
});

Feature Flag Experiments​

There is nothing special you have to do for feature flag experiments. Just evaluate the feature flag like you would normally do. If the user is put into an experiment as part of the feature flag, it will call the trackingCallback automatically in the background.

// If this has an active experiment and the user is included,
// it will call trackingCallback automatically
const newLogin = gb.isOn("new-signup-form");

If the experiment came from a feature rule, result.featureId in the trackingCallback will contain the feature id, which may be useful for tracking/logging purposes.

Deferred Tracking​

Sometimes, you aren't able to track analytics events from Node.js and you need to do it from the front-end instead.

If that is the case for your app, do not specify a trackingCallback in the constructor. This will queue up tracking calls in the GrowthBook instance.

You can export the queued tracking calls with the getDeferredTrackingCalls() method. The result is a serializable JSON object:

const tracks = gb.getDeferredTrackingCalls();

Send those down to your front-end and you can fire them in one of two ways:

If Using GrowthBook on the Front-End​

If you are already using the JavaScript or React SDK on the front-end, you can import with setDeferredTrackingCalls. This does not fire them automatically. You must call fireDeferredTrackingCalls after.

gb.setDeferredTrackingCalls(tracks);
gb.fireDeferredTrackingCalls();

This will use the trackingCallback configured on your front-end GrowthBook instance.

Standalone Tracker​

If you do NOT have a client-side GrowthBook instance, you can still fire these tracking calls with a small custom client-side script:

tracks.forEach(({experiment, result}) => {
  // Example using Segment.io
  analytics.track("Experiment Viewed", {
    experimentId: experiment.key,
    variationId: result.key,
  });
})

Sticky Bucketing​

Sticky bucketing ensures that users see the same experiment variant, even when user session, user login status, or experiment parameters change. See the Sticky Bucketing docs for more information. If your organization and experiment supports sticky bucketing, you must implement an instance of the StickyBucketService to use Sticky Bucketing. The JS SDK exports several implementations of this service for common use cases, or you may build your own:

  • ExpressCookieStickyBucketService — For NodeJS/Express controller-level bucket persistence using browser cookies; intended to be interoperable with BrowserCookieStickyBucketService. Assumes cookie-parser is implemented (can be polyfilled). Cookie attributes can also be configured. The default cookie expiry is 180 days; override by passing maxAge: {ms} into the constructor's cookieAttributes.

  • RedisStickyBucketService — For NodeJS Redis-based bucket persistence. Requires an ioredis Redis client instance to be passed in.

  • Build your own — Implement the abstract StickyBucketService class and connect to your own data store, or custom wrap multiple service implementations (ex: read/write to both cookies and Redis).

Implementing most StickyBucketService implementations is straightforward and works with minimal setup. For instance, to use the ExpressCookieStickyBucketService:

const { ExpressCookieStickyBucketService } = require("@growthbook/growthbook");

app.use(function(req, res, next) {
  // Create a GrowthBook instance and store in the request
  req.growthbook = new GrowthBook({
    apiHost: "https://cdn.growthbook.io",
    clientKey: "sdk-abc123",
    stickyBucketService: new ExpressCookieStickyBucketService({
      req,
      res
    }),
  })
})

TypeScript​

When used in a TypeScript project, GrowthBook includes basic type inference out of the box:

// Type will be `string` based on the fallback provided ("blue")
const color = gb.getFeatureValue("button-color", "blue");

// You can manually specify types as well
// feature.value will be type `number`
const feature = gb.evalFeature<number>("font-size");
console.log(feature.value);

// Experiments will use the variations to infer the return value
// result.value will be type "string"
const result = gb.run({
  key: "my-test",
  variations: ["blue", "green"],
});

Strict Typing​

If you want to enforce stricter types in your application, you can do that when creating the GrowthBook instance:

// Define all your feature flags and types here
interface AppFeatures {
  "button-color": string;
  "font-size": number;
  "newForm": boolean;
}

// Pass into the GrowthBook instance
const gb = new GrowthBook<AppFeatures>({
  ...
});

Now, all feature flag methods will be strictly typed.

// feature.value will by type `number`
const feature = gb.evalFeature("font-size");
console.log(feature.value);

// Typos will cause compile-time errors
gb.isOn("buton-color"); // "buton" instead of "button"

Instead of defining the AppFeatures interface manually like above, you can auto-generate it from your GrowthBook account using the GrowthBook CLI.

Updating​

As a general philosophy, we aim to keep the SDK 100% backwards compatible at all times. View the Changelog for a complete list of all SDK changes.

GrowthBook Instance (reference)​

Attributes​

You can specify attributes about the current user and request. These are used for two things:

  1. Feature targeting (e.g. paid users get one value, free users get another)
  2. Assigning persistent variations in A/B tests (e.g. user id "123" always gets variation B)

The following are some commonly used attributes, but use whatever makes sense for your application.

new GrowthBook({
  attributes: {
    id: "123",
    loggedIn: true,
    deviceId: "abc123def456",
    company: "acme",
    paid: false,
    url: "/pricing",
    browser: "chrome",
    mobile: false,
    country: "US",
  },
});

Updating Attributes​

If attributes change, you can call setAttributes() to update. This will completely overwrite any existing attributes. To do a partial update, use the following pattern:

gb.setAttributes({
  // Only update the `url` attribute, keep the rest the same
  ...gb.getAttributes(),
  url: "/new-page"
})

Secure Attributes​

When secure attribute hashing is enabled, all targeting conditions in the SDK payload referencing attributes with datatype secureString or secureString[] will be anonymized via SHA-256 hashing. This allows you to safely target users based on sensitive attributes. You must enable this feature in your SDK Connection for it to take effect.

If your SDK Connection has secure attribute hashing enabled, you will need to manually hash any secureString or secureString[] attributes that you pass into the GrowthBook SDK.

To hash an attribute, use a cryptographic library with SHA-256 support, and compute the SHA-256 hashed value of your attribute plus your organization's secure attribute salt.

const salt = "f09jq3fij"; // Your organization's secure attribute salt (see Organization Settings)

// hashing a secureString attribute
const userEmail = sha256(salt + user.email);

// hashing an secureString[] attribute
const userTags = user.tags.map(tag => sha256(salt + tag));

gb.setAttributes({
  id: user.id,
  loggedIn: true,
  email: userEmail,
  tags: userTags,
});

await gb.init();

// In this example, we are using Node.js's built-in crypto library
function sha256(str) {
  return crypto.createHash("sha256").update(str).digest("hex");
}

Feature Usage Callback​

GrowthBook can fire a callback whenever a feature is evaluated for a user. This can be useful to update 3rd party tools like NewRelic or DataDog.

new GrowthBook({
  onFeatureUsage: (featureKey, result) => {
    console.log("feature", featureKey, "has value", result.value);
  },
});

The result argument is the same thing returned from gb.evalFeature.

Note: If you evaluate the same feature multiple times (and the value doesn't change), the callback will only be fired the first time.

evalFeature​

In addition to the isOn and getFeatureValue helper methods, there is the evalFeature method that gives you more detailed information about why the value was assigned to the user.

// Get detailed information about the feature evaluation
const result = gb.evalFeature("my-feature");

// The value of the feature (or `null` if not defined)
console.log(result.value);

// Why the value was assigned to the user
// One of: `override`, `unknownFeature`, `defaultValue`, `force`, or `experiment`
console.log(result.source);

// The string id of the rule (if any) which was used
console.log(result.ruleId);

// Information about the experiment (if any) which was used
console.log(result.experiment);

// The result of the experiment (or `undefined`)
console.log(result.experimentResult);

Inline Experiments​

Instead of declaring all features up-front in the context and referencing them by ids in your code, you can also just run an experiment directly. This is done with the gb.run method:

// These are the only required options
const { value } = gb.run({
  key: "my-experiment",
  variations: ["red", "blue", "green"],
});

Customizing the Traffic Split​

By default, this will include all traffic and do an even split between all variations. There are 2 ways to customize this behavior:

// Option 1: Using weights and coverage
gb.run({
  key: "my-experiment",
  variations: ["red", "blue", "green"],
  // Only include 10% of traffic
  coverage: 0.1,
  // Split the included traffic 50/25/25 instead of the default 33/33/33
  weights: [0.5, 0.25, 0.25],
});

// Option 2: Specifying ranges
gb.run({
  key: "my-experiment",
  variations: ["red", "blue", "green"],
  // Identical to the above
  // 5% of traffic in A, 2.5% each in B and C
  ranges: [
    [0, 0.05],
    [0.5, 0.525],
    [0.75, 0.775],
  ],
});

Hashing​

We use deterministic hashing to assign a variation to a user. We hash together the user's id and experiment key, which produces a number between 0 and 1. Each variation is assigned a range of numbers, and whichever one the user's hash value falls into will be assigned.

You can customize this hashing behavior:

gb.run({
  key: "my-experiment",
  variations: ["A", "B"],

  // Which hashing algorithm to use
  // Version 2 is the latest and the one we recommend
  hashVersion: 2,

  // Use a different seed instead of the experiment key
  seed: "abcdef123456",

  // Use a different user attribute (default is `id`)
  hashAttribute: "device_id",
});

Note: For backwards compatibility, if no hashVersion is specified, it will fall back to using version 1, which is deprecated. In the future, version 2 will become the default. We recommend specifying version 2 now for all new experiments to avoid migration issues down the line.

Meta Info​

You can also define meta info for the experiment and/or variations. These do not affect the behavior, but they are passed through to the trackingCallback, so they can be used to annotate events.

gb.run({
  key: "results-per-page",
  variations: [10, 20],

  // Experiment meta info
  name: "Results per Page",
  phase: "full-traffic"

  // Variation meta info
  meta: [
    {
      key: "control",
      name: "10 Results per Page",
    },
    {
      key: "variation",
      name: "20 Results per Page",
    },
  ]
})

Mutual Exclusion​

Sometimes you want to run multiple conflicting experiments at the same time. You can use the filters setting to run mutually exclusive experiments.

We do this using deterministic hashing to assign users a value between 0 and 1 for each filter.

// Will include 60% of users - ones with a hash between 0 and 0.6
gb.run({
  key: "experiment-1",
  variation: [0, 1],
  filters: [
    {
      seed: "pricing",
      attribute: "id",
      ranges: [[0, 0.6]]
    }
  ]
});


// Will include the other 40% of users - ones with a hash between 0.6 and 1
gb.run({
  key: "experiment-2",
  variation: [0, 1],
  filters: [
    {
      seed: "pricing",
      attribute: "id",
      ranges: [[0.6, 1.0]]
    }
  ]
});

Note - If a user is excluded from an experiment due to a filter, the rule will be skipped and the next matching rule will be used instead.

Holdout Groups​

To use global holdout groups, use a nested experiment design:

// The value will be `true` if in the holdout group, otherwise `false`
const holdout = gb.run({
  key: "holdout",
  variations: [true, false],
  // 10% of users in the holdout group
  weights: [0.1, 0.9]
});

// Only run your main experiment if the user is NOT in the holdout
if (!holdout.value) {
  const res = gb.run({
    key: "my-experiment",
    variations: ["A", "B"]
  })
}

Targeting Conditions​

You can also define targeting conditions that limit which users are included in the experiment. These conditions are evaluated against the attributes passed into the GrowthBook context. The syntax for conditions is based on the MongoDB query syntax and is straightforward to read and write.

For example, if the attributes are:

{
  "id": "123",
  "browser": {
    "vendor": "firefox",
    "version": 94
  },
  "country": "CA"
}

The following condition would evaluate to true and the user would be included in the experiment:

gb.run({
  key: "my-experiment",
  variation: [0, 1],
  condition: {
    "browser.vendor": "firefox",
    "country": {
      "$in": ["US", "CA", "IN"]
    }
  }
})

Inline Experiment Return Value​

A call to gb.run(experiment) returns an object with a few useful properties:

const {
  value,
  key,
  name,
  variationId,
  inExperiment,
  hashUsed,
  hashAttribute,
  hashValue,
} = gb.run({
  key: "my-experiment",
  variations: ["A", "B"],
});

// If user is included in the experiment
console.log(inExperiment); // true or false

// The index of the assigned variation
console.log(variationId); // 0 or 1

// The value of the assigned variation
console.log(value); // "A" or "B"

// The key and name of the assigned variation (if specified in `meta`)
console.log(key); // "0" or "1"
console.log(name); // ""

// If the variation was randomly assigned by hashing
console.log(hashUsed);

// The user attribute that was hashed
console.log(hashAttribute); // "id"

// The value of that attribute
console.log(hashValue); // e.g. "123"

The inExperiment flag will be false if the user was excluded from being part of the experiment for any reason (e.g. failed targeting conditions).

The hashUsed flag will only be true if the user was randomly assigned a variation. If the user was forced into a specific variation instead, this flag will be false.

Feature Definitions (reference)​

The feature definition JSON file contains information about all of the features in your application.

Each feature consists of a unique key, a list of possible values, and rules for how to assign those values to users.

{
  "feature-1": {...},
  "feature-2": {...},
  "another-feature": {...},
}

Basic Feature​

An empty feature always has the value null:

{
  "my-feature": {}
}

Default Values​

You can change the default assigned value with the defaultValue property:

{
  "my-feature": {
    defaultValue: "green"
  }
}

Rules​

You can override the default value with Rules.

Rules give you fine-grained control over how feature values are assigned to users. There are 2 types of feature rules: force and experiment. Force rules give the same value to everyone. Experiment rules assign values to users randomly.

Rule Ids​

Rules can specify a unique identifier with the id property. This can help with debugging and QA by letting you see exactly why a specific value was assigned to a user.

Rule Conditions​

Rules can optionally define targeting conditions that limit which users the rule applies to. These conditions are evaluated against the attributes passed into the GrowthBook context. The syntax for conditions is based on the MongoDB query syntax and is straightforward to read and write.

For example, if the attributes are:

{
  "id": "123",
  "browser": {
    "vendor": "firefox",
    "version": 94
  },
  "country": "CA"
}

The following condition would evaluate to true:

{
  "browser.vendor": "firefox",
  "country": {
    "$in": ["US", "CA", "IN"]
  }
}

If a condition evaluates to false, the rule will be skipped. This means you can chain rules together with different conditions to support even the most complex use cases.

Force Rules​

Force rules do what you'd expect - force a specific value for the feature

// Firefox users in the US or Canada get "green"
// Everyone else gets the default "blue"
{
  "button-color": {
    defaultValue: "blue",
    rules: [
      {
        id: "rule-123",
        condition: {
          browser: "firefox",
          country: {
            $in: ["US", "CA"]
          }
        },
        force: "green"
      }
    ],
  }
}
Gradual Rollouts​

You can specify a range for your rule, which determines what percent of users will get the rule applied to them. Users who do not get the rule applied will fall through to the next matching rule (or default value). You can also specify a seed that will be used for hashing.

In order to figure out if a user is included or not, we use deterministic hashing. By default, we use the user attribute id for this, but you can override this by specifying hashAttribute for the rule:

This is useful for gradually rolling out features to users (start with a small range and slowly increase).

{
  "new-feature": {
    defaultValue: false,
    rules: [
      {
        force: true,
        hashAttribute: "device-id",
        seed: 'new-feature-rollout-abcdef123',
        // 20% of users
        range: [0, 0.2]
        // Increase to 40%:
        // range: [0, 0.4]
      }
    ]
  }
}

Experiment Rules​

Experiment rules let you adjust the percent of users who get randomly assigned to each variation. This can either be used for hypothesis-driven A/B tests or to simply mitigate risk by gradually rolling out new features to your users.

// Each variation gets assigned to a random 1/3rd of users
{
  "image-size": {
    rules: [
      {
        variations: ["small", "medium", "large"]
      }
    ]
  }
}
Customizing the Traffic Split​

By default, an experiment rule will include all traffic and do an even split between all variations. There are 2 ways to customize this behavior:

// Option 1: Using weights and coverage
{
  variations: ["red", "blue", "green"],
  // Only include 10% of traffic
  coverage: 0.1,
  // Split the included traffic 50/25/25 instead of the default 33/33/33
  weights: [0.5, 0.25, 0.25]
}

// Option 2: Specifying ranges
{
  variations: ["red", "blue", "green"],
  // Identical to the above
  // 5% of traffic in A, 2.5% each in B and C
  ranges: [
    [0, 0.05],
    [0.5, 0.525],
    [0.75, 0.775]
  ]
}

A user is assigned a number from 0 to 1 and whichever variation's range includes their number will be assigned to them.

Variation Meta Info​

You can use the meta setting to provide additional info about the variations such as name.

{
  "image-size": {
    rules: [
      {
        variations: ["sm", "md", "lg"],
        ranges: [
          [0, 0.5],
          [0.5, 0.75],
          [0.75, 1.0]
        ],
        meta: [
          {
            key: "control",
            name: "Small",
          },
          {
            key: "v1",
            name: "Medium",
          },
          {
            key: "v2",
            name: "Large",
          }
        ]
      }
    ]
  }
}
Tracking Key and Name​

When a user is assigned a variation, we call the trackingCallback function so you can record the exposure with your analytics event tracking system. By default, we use the feature id to identify the experiment, but this can be overridden if needed with the key setting. You can also optionally provide a human-readable name.

{
  "feature-1": {
    rules: [
      {
        // Use "my-experiment" as the key instead of "feature-1"
        key: "my-experiment",
        name: "My Experiment",
        variations: ["A", "B"]
      }
    ]
  },
}
Hash Attribute​

We use deterministic hashing to make sure the same user always gets assigned the same value. By default, we use the attribute id, but this can be overridden with the hashAttribute setting:

const gb = new GrowthBook({
  attributes: {
    id: "123",
    company: "acme",
  },
  features: {
    "my-feature": {
      rules: [
        // All users with the same "company" value
        // will be assigned the same variation
        {
          variations: ["A", "B"],
          hashAttribute: "company",
        },
        // If "company" is empty for the user (e.g. if they are logged out)
        // The experiment will be skipped and fall through to this next rule
        {
          force: "A",
        },
      ],
    },
  },
});
Filters​

Sometimes you want to run multiple conflicting experiments at the same time. You can use the filters setting to run mutually exclusive experiments.

We do this using deterministic hashing to assign users a value between 0 and 1 for each filter.

{
  "feature1": {
    rules: [
      // Will include 60% of users - ones with a hash between 0 and 0.6
      {
        variations: [false, true],
        filters: [
          {
            seed: "pricing",
            attribute: "id",
            ranges: [[0, 0.6]]
          }
        ]
      }
    ]
  },
  "feature2": {
    rules: [
      // Will include the other 40% of users - ones with a hash between 0.6 and 1
      {
        variations: [false, true],
        filters: [
          {
            seed: "pricing",
            attribute: "id",
            ranges: [[0.6, 1.0]]
          }
        ]
      },
    ]
  }
}

Note - If a user is excluded from an experiment due to a filter, the rule will be skipped and the next matching rule will be used instead.

Examples​