@envflags/js-sdk

The envflags.com SDK for evaluating feature flags in browsers, Node.js, and Workers.

Use the client entry in browsers and front-end bundles. It fetches once at initialize() and has no background polling. Use the server entry in Node.js, Workers, and other long-lived processes that should poll for updates.

import { createClient } from "@envflags/js-sdk";

const flags = await createClient("client_…").initialize();
flags.setContext({ key: "user-123", country: "BE" });

const enabled = flags.boolVariation("new-checkout", false);

@envflags/js-sdk/client is the same module. Call setContext once and omit context on later reads. Call refresh() when the application should check for a newer payload; the client never schedules that itself. Supply a previously persisted payload as bootstrap to remain available when the first network request fails, including when your backend inlines a client payload into the page. Once initialized, refresh failures keep the last-known payload active. Typed variation methods always fall back to the caller's default when a flag is missing or has the wrong value type. Context is optional: flags that do not depend on who is asking still evaluate off/fallthrough without it.

Server

import { createServer } from "@envflags/js-sdk/server";

const flags = await createServer("server_…").initialize();
const enabled = flags.boolVariation("new-checkout", false, {
  key: "user-123",
  country: "BE",
});

flags.close();

Skip setContext and pass context as the last argument so one process can evaluate many users. The server polls every 30 seconds and fetches a new payload only when its version changes. Set pollIntervalMs: false to refresh manually. Call close() to stop the timer.

React

Define the application's flags once with any Standard Schema validator. The resulting API knows every flag key, return type, and fallback value. Remote values are validated before they reach application code, including structured JSON flags.

import { flag } from "@envflags/js-sdk";
import { defineFlags } from "@envflags/js-sdk/react";
import { z } from "zod";

const envflags = defineFlags({
  "new-checkout": flag(z.boolean(), false),
  "checkout-config": flag(
    z.object({
      layout: z.enum(["compact", "comfortable"]),
      maximumItems: z.number().int().positive(),
    }),
    { layout: "comfortable", maximumItems: 20 },
  ),
});

const client = envflags.createClient("client_…");

function App() {
  return (
    <envflags.EnvflagsProvider client={client} context={{ key: "user-123" }}>
      <Checkout />
    </envflags.EnvflagsProvider>
  );
}

function Checkout() {
  const enabled = envflags.useFlag("new-checkout"); // boolean
  const config = envflags.useFlag("checkout-config"); // fully typed object
  return enabled ? <NewCheckout /> : <OldCheckout />;
}

Schemas must validate synchronously. Flags can contain booleans, numbers, strings, null, arrays, or objects. Defaults are validated immediately. An invalid remote variation reports through the client's onError callback and resolves to its registered default. useFlag accepts an optional second argument to override the provider context for one evaluation.

The provider initializes its client and re-renders consumers when a new payload arrives, including after an explicit refresh(). Pass onFetched to run your own loading UI when that first fetch settles, including when initialization fails and flags stay on their defaults. Later refresh() calls do not invoke it. Prefer bootstrapping the client from your server so the browser does not need its own fetch. The provider does not dispose the client when it unmounts because the client may be shared.

The low-level variation and typed variation methods remain available for dynamic flag keys and gradual migration.