Skip to content
Featureflip Docs

Node.js Feature Flags Quickstart

This guide gets you from zero to evaluating a feature flag in a Node.js application. The SDK wraps @featureflip/js with Node.js-specific defaults for a simpler setup.

Prerequisites

Section titled “Prerequisites”
  • A Featureflip account with at least one feature flag created
  • An SDK key from your environment settings
  • Node.js 20.19.0+

Install

Section titled “Install”
Terminal window
npm install @featureflip/node-sdk

Initialize the client

Section titled “Initialize the client”
import { FeatureflipClient } from "@featureflip/node-sdk";


const client = await FeatureflipClient.create({
  sdkKey: "your-sdk-key",
});

FeatureflipClient.create() fetches your flag configuration and resolves once initialization is complete.

You can also obtain a client synchronously and wait manually:

const client = FeatureflipClient.get({ sdkKey: "your-sdk-key" });
await client.waitForInitialization();

FeatureflipClient.get() is the only way to obtain a client — the public constructor was removed in v2.0. The factory dedupes by SDK key, so calling get() multiple times with the same key always returns a handle pointing at one shared underlying client. This makes the SDK safe to use from per-request handlers and DI containers without accidentally opening duplicate streaming connections. See Lifetime in the reference for details.

Evaluate a flag

Section titled “Evaluate a flag”
const showBanner = client.boolVariation(
  "new-banner",
  { user_id: "user-123" },
  false,
);


if (showBanner) {
  console.log("Showing the new banner");
} else {
  console.log("Using the default experience");
}

The third argument is the default value returned when the flag is not found or evaluation fails.

Other variation methods are available for different value types:

const color = client.stringVariation("banner-color", { user_id: "user-123" }, "blue");
const limit = client.numberVariation("rate-limit", { user_id: "user-123" }, 100);
const config = client.jsonVariation("ui-config", { user_id: "user-123" }, {});

Clean up

Section titled “Clean up”

When your application shuts down, close the client to flush pending analytics events and stop background connections:

await client.close();

How it works

Section titled “How it works”

The Node.js SDK (@featureflip/node) wraps the core @featureflip/js evaluation engine with a Node-specific transport layer. It evaluates flags locally in your process — boolVariation() and other variation calls are synchronous reads from an in-memory store, so they never block the event loop or add latency to your Express/Fastify/Hono request handlers.

waitForInitialization() returns a Promise that resolves once the initial flag configuration has been fetched over HTTPS. After that, the SDK maintains an SSE streaming connection on the event loop to receive configuration updates in near-real-time. If SSE is unavailable, it falls back to an interval-based polling loop every 30 seconds. Both mechanisms use Node’s native http/https modules, so they integrate cleanly with the event loop without spawning threads or child processes.

Call await client.close() during graceful shutdown (e.g., in a SIGTERM handler) to close the SSE connection and flush pending analytics events. If the streaming connection drops mid-operation, the SDK continues serving the last known configuration while it attempts to reconnect in the background.

Troubleshooting

Section titled “Troubleshooting”

waitForInitialization() rejects or hangs

The most common cause is an incorrect SDK key or a network issue reaching the evaluation API. Verify your SDK key matches the environment you are targeting (each environment has a unique key). If you are behind a corporate proxy or firewall, ensure outbound HTTPS traffic to eval.featureflip.io is allowed.

Flags return default values after successful init

This usually means the flag key does not match exactly. Flag keys are case-sensitive — new-banner and New-Banner are different flags. Check the dashboard to confirm the key, and make sure the flag is enabled in the environment matching your SDK key.

TypeScript type errors with variation methods

If you are using strict TypeScript, ensure you pass the correct type for the default value. boolVariation expects a boolean default, stringVariation expects a string, and so on. Passing null or undefined as a default is not supported — always provide a typed fallback.

Next steps

Section titled “Next steps”