Skip to content
Featureflip Docs

JavaScript Feature Flags Quickstart

This guide gets you from zero to evaluating a feature flag in a JavaScript or TypeScript application. The SDK works in both Node.js and browser environments.

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+ (for Node usage) or a modern browser

Install

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

Initialize the client

Section titled “Initialize the client”

The SDK ships separate platform adapters for Node.js and browsers. Import the one that matches your runtime.

Node.js

Section titled “Node.js”
import { FeatureflipClient, createNodePlatform } from "@featureflip/js";


const client = FeatureflipClient.get(
  {
    sdkKey: "your-sdk-key",
    baseUrl: "https://eval.featureflip.io",
  },
  createNodePlatform()
);


await client.waitForInitialization();

Browser

Section titled “Browser”
import {
  FeatureflipClient,
  createBrowserPlatform,
} from "@featureflip/js/browser";


const client = FeatureflipClient.get(
  {
    sdkKey: "your-sdk-key",
    baseUrl: "https://eval.featureflip.io",
  },
  createBrowserPlatform()
);


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 returns handles 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.

waitForInitialization() fetches your flag configuration from the evaluation API. It rejects if the initial fetch fails or times out.

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 JS SDK is a server-side SDK that evaluates flags locally in your process. On initialization, it fetches the full flag configuration from the Featureflip evaluation API and opens an SSE (Server-Sent Events) connection that streams updates in real-time whenever flags change in the dashboard. Because evaluation happens locally, boolVariation() and other variation calls return immediately with no network latency.

Server-side vs client-side SDKs

Use the JS SDK (this guide) when flags are evaluated in a Node.js backend, a build pipeline, or any server-side environment where you control the runtime. It has access to the full flag configuration and evaluates rules locally.

If you are building a browser application or mobile app where your end users run the code, use a client-side SDK instead (such as the Browser SDK or React SDK). Client-side SDKs receive pre-evaluated flag values from the server — they never expose your full rule configuration to end users.

The SDK provides separate platform adapters for Node.js and browsers. The Node adapter uses node:http for requests, while the browser adapter uses the Fetch API.

Troubleshooting

Section titled “Troubleshooting”

waitForInitialization() rejects with a network error

Verify your SDK key and that your application can reach the evaluation API (eval.featureflip.io) over HTTPS. If you are using the browser platform in development, check that CORS is not blocking the request — the evaluation API allows cross-origin requests, but browser extensions or proxy configurations may interfere.

Flags return default values after successful init

Flag keys are case-sensitive — new-banner and New-Banner are different flags. Verify the key in the dashboard matches your code exactly. Also confirm the flag is enabled in the environment your SDK key belongs to.

Cannot find module '@featureflip/sdk/browser'

This export is available from version 1.0.0+. If you see this error, check your installed version with npm list @featureflip/sdk. Also ensure your bundler supports package.json exports — older bundlers or TypeScript configurations with moduleResolution: "node" may not resolve subpath exports correctly. Set moduleResolution to "bundler" or "node16" in your tsconfig.json.

Next steps

Section titled “Next steps”