Node.js SDK

The Node.js SDK is built for trusted server-side applications. It loads one environment snapshot, evaluates flags locally, and refreshes configuration in the background.

Install and initialize

Install the ESM-only SDK in a Node.js 22 or newer application:

npm install @featuregate/node

Create one client per runtime key and reuse it for the lifetime of the process. initialize() loads the first remote snapshot and starts polling.

import { FeatureGate } from "@featuregate/node";

export const featuregate = new FeatureGate({
runtimeApiKey: process.env.FEATUREGATE_RUNTIME_KEY!,
});

await featuregate.initialize();

Configuration

FeatureGate requires a runtimeApiKey, an in-memory flags snapshot, or both.

Errors from initialize() and refresh() reject their promises. onError is used only for automatic refresh failures.

Evaluate typed flags

Every evaluation takes an explicit default. The SDK uses it when the flag is missing or its stored value does not match the selected getter.

const enabled = featuregate.getBooleanValue("checkout", false, context);
const heading = featuregate.getStringValue("checkout-heading", "Checkout", context);
const pageSize = featuregate.getNumberValue("page-size", 25, context);
const theme = featuregate.getObjectValue("theme", { mode: "system" }, context);

Each value getter has a corresponding details getter:

Details include the final value, the evaluation reason, and whether the SDK usedDefault.

Evaluation context

Use targetingKey for a stable subject identifier and attributes for application-specific data. Nested attributes are addressed by dot-separated paths in targeting rules.

const context = {
targetingKey: "customer-123",
attributes: {
  account: {
    id: "account-456",
    plan: "pro",
  },
  country: "AU",
},
};

const enabled = featuregate.getBooleanValue("checkout", false, context);

Stable identifiers keep percentage-rollout assignment deterministic across evaluations.

Refresh and shutdown

The client polls every 30 seconds by default and uses ETag revalidation. Call refresh() when you need to request configuration immediately:

const result = await featuregate.refresh();

if (result.status === "updated") {
  console.log(`Loaded snapshot ${result.version}`);
}

Failed refreshes keep the last successful snapshot available. Call close() during application shutdown to stop automatic polling; the last snapshot remains available for evaluation.

Errors and fallbacks

Testing and offline evaluation

For tests and local development, provide an in-memory flags snapshot without a runtime key. Local instances are ready immediately and do not need initialize().

const featuregate = new FeatureGate({
  flags: {
    checkout: { defaultValue: true },
  },
});

featuregate.getBooleanValue("checkout", false); // true

Next steps