Node.js SDK

The RocketFlag Node.js SDK provides a convenient wrapper around the RocketFlag API, handling authentication, caching, and environment configuration for you.

Installation

Install the SDK via npm or yarn:

npm install @rocketflag/node-sdk

Basic Usage

Import and initialize the client:

import createRocketflagClient from "@rocketflag/node-sdk";

// Initialize the client
const rocketflag = createRocketflagClient();

async function checkFeature() {
  const flagId = "ABC123def456";

  try {
    const flag = await rocketflag.getFlag(flagId);

    if (flag.enabled) {
      console.log(`Feature "${flag.name}" is enabled!`);
    }
  } catch (error) {
    console.error("Error fetching flag:", error.message);
  }
}

Advanced Usage

Working with Cohorts

Pass a cohort identifier to target specific users:

const flag = await rocketflag.getFlag(flagId, {
  cohort: "user@example.com"
});

Attributes and sticky rollouts

Add a targetingKey for sticky percentage rollouts, and any other keys as audience attributes:

const flag = await rocketflag.getFlag(flagId, {
  targetingKey: "user-42",
  plan: "pro",
  country: "AU"
});

Percentage rollouts are sticky per key: the same targetingKey (or, without one, the same cohort) gets the same answer every time, so send a stable user identifier. Other keys are matched against the flag’s audience and are only read when the flag has one. Matching is exact and case-sensitive, and an attribute you do not send never matches. cohort, env and targetingKey are reserved and cannot be audience attributes. See Sticky rollouts.

Every context value must be a string, number, or boolean. Leave out an attribute you do not have rather than passing it as undefined. In TypeScript, { plan: user.plan } where plan may be undefined is a compile error. An optional property on an object you have typed yourself, or undefined passed from JavaScript, throws at runtime instead. UserContext and ContextValue are exported for type annotations. Because UserContext has a string index signature, declare custom context objects using type rather than interface, or spread them: getFlag(flagId, { ...context }).

Working with Group Flags (Environments)

When using Group Flags, you must specify the environment (environment names may contain letters, numbers, hyphens, and underscores):

const flag = await rocketflag.getFlag(flagId, {
  env: "production"
});

Custom Configuration

You can customize the API URL or version if necessary:

const apiVersion = "v1";
const apiUrl = "https://your-custom-proxy.com";
const rocketflag = createRocketflagClient(apiVersion, apiUrl);

Caching Responses

To avoid hitting the API on every check, enable an in-memory cache by passing a default ttlSeconds (the third argument) when creating the client. Cached entries are keyed by flag ID and the user context, so different cohorts or environments still resolve independently.

// Cache flag responses for 5 minutes.
const rocketflag = createRocketflagClient(undefined, undefined, { ttlSeconds: 300 });

// First call hits the API; subsequent calls within 5 minutes are served from cache.
const flag = await rocketflag.getFlag("ABC123def456", { cohort: "beta" });

Override the TTL for a single call, or disable caching for that call by passing 0:

// Force a fresh fetch, bypassing the cache.
const flag = await rocketflag.getFlag("ABC123def456", {}, { ttlSeconds: 0 });

// Use a shorter TTL just for this call.
const flag = await rocketflag.getFlag("ABC123def456", {}, { ttlSeconds: 10 });

Caching is opt-in: without a client default or per-call TTL, every call goes to the API. Each distinct context is its own cache entry, so a targetingKey per user means an entry per user. The cache holds at most 10,000 entries by default and evicts the least recently used (LRU) entry when full. You can configure this limit with maxEntries:

// Cache flag responses for 5 minutes, capping the cache at 50,000 entries.
const rocketflag = createRocketflagClient(undefined, undefined, {
  ttlSeconds: 300,
  maxEntries: 50_000,
});

Error Handling

The SDK can throw three typed errors:

• APIError — the API returned a non-ok response. Carries the status and statusText.
• InvalidResponseError — the response wasn’t valid JSON or didn’t match the expected shape.
• NetworkError — a network failure, such as a dropped connection.

import { APIError, InvalidResponseError, NetworkError } from "@rocketflag/node-sdk/errors";

try {
  const flag = await rocketflag.getFlag("ABC123def456");
  // ...
} catch (error) {
  if (error instanceof APIError) {
    console.error(`API Error: ${error.status} ${error.statusText}`);
  } else if (error instanceof InvalidResponseError) {
    console.error(`Invalid Response Error: ${error.message}`);
  } else if (error instanceof NetworkError) {
    console.error(`Network Error: ${error.message}`);
  } else {
    console.error("An unknown error occurred", error);
  }
}