Node.js quickstart

@flagwire/sdk-node downloads a versioned environment bundle, validates it, and evaluates flags locally. It requires Node.js 22.4 or newer.

Install

pnpm add @flagwire/sdk-node

Create one server client

import { createServerClient } from "@flagwire/sdk-node";

const flags = createServerClient({
  serverKey: process.env.FLAGWIRE_SERVER_KEY!,
});

Server keys begin with sk_live_. Store them in a secret manager or process environment. Never commit, log, place in command arguments, or send them to a browser.

Create one long-lived client per process rather than one client per request.

Bound initialization

await flags.waitForInitialization({ timeoutMs: 5_000 });

A bounded wait lets your service start predictably during an upstream outage. Invalid, unavailable, or revoked bundle state fails to the default supplied by your code.

Evaluate locally

const redesigned = flags.evaluate(
  "checkout-redesign",
  {
    key: "user-123",
    attributes: { region: "ap-south", appVersion: "2.4.1" },
  },
  false,
);

Use evaluateDetail() for the value, variant, and evaluation reason. Use allFlags() when one request needs a snapshot of every flag.

const detail = flags.evaluateDetail("checkout-redesign", { key: "user-123" }, false);

const snapshot = flags.allFlags({ key: "user-123" });

For server-rendered browser applications, build a compatible bootstrap from the active server bundle. Serialize it with your framework’s safe JSON mechanism.

const bootstrap = flags.browserSnapshot({ key: "user-123" });

Shut down cleanly

async function shutdown() {
  await flags.close();
  process.exit(0);
}

process.once("SIGTERM", shutdown);
process.once("SIGINT", shutdown);

close() stops polling and streaming, attempts to flush queued exposure events, and releases the client’s background resources.

Generate flag types

pnpm dlx flagwire-typegen --out src/flags.gen.ts

Provide FLAGWIRE_SERVER_KEY through your shell or CI secret environment before running the command. Do not paste a live key into source, a package script, or shell history.

import "./flags.gen";

evaluate() then infers known flag keys and their value types.

Configuration

Option	Required	Default	Purpose
serverKey	Yes	—	Secret key beginning with sk_live_
baseUrl	No	https://edge.flagwire.dev	FlagWire edge endpoint
pollIntervalMs	No	30000	Refresh interval while a stream is not healthy
stream	No	true	Listen for version notifications when WebSockets are available

Next: targeting reference or bundle format.