Browser SDK

Use @featuregate/browser when flag checks must run in browser JavaScript. Browser clients use publishable client keys, not secret server runtime keys. A client key is bound to one project environment, allowed origins, and the client:evaluate scope.

Browser evaluation calls the shared POST /v1/evaluate route. It can evaluate only flags that are explicitly exposed to clients for that environment.

Before you install

Create the browser key from the console environment where the flag should be evaluated. Add exact allowed origins such as https://app.example.com; paths, wildcards, and missing origins are rejected. Then open each flag's environment defaults and enable client exposure for the flags this browser app may evaluate.

Install

npm install @featuregate/browser

Create a client

import { createFeatureGateBrowserClient } from "@featuregate/browser";

export const featuregate = createFeatureGateBrowserClient({
clientApiKey: "fg_pk_test_0123456789abcdef0123456789abcdef0123456789abcdef",
// Optional for local/dev proxies:
// apiBaseUrl: "http://api.featuregate.localhost",
});

Evaluate flags

Every browser evaluation sends a typed default. Calls in the same microtask with the same attributes are batched into one request, and identical in-flight evaluations share a promise.

const enabled = await featuregate.getBoolean("new-checkout", {
defaultValue: false,
attributes: {
  user: { id: "user_123" },
  account: { plan: "pro" },
},
});

isEnabled is available as a boolean alias when that reads better at the call site.

Refresh a batch

Use refresh when a UI wants to re-evaluate a known set of flags after attributes change or a user retries from an error state.

const results = await featuregate.refresh([
{ key: "new-checkout", defaultValue: false },
{ key: "checkout-title", defaultValue: "Checkout" },
]);

Call close() during teardown if you want to clear pending in-flight work explicitly.

Failure behavior

Network errors, timeouts, rate limits, and 5xx responses return caller defaults from the typed helpers. Authentication and request-configuration failures throw typed errors so you can fix the key, origin, or request shape.

The browser SDK does not use localStorage, IndexedDB, cookies, or other durable browser storage.

Client keys cannot fetch /v1/snapshot, subscribe to /v1/snapshot/stream, call management routes, or evaluate flags that are not marked client-exposed for the key's environment.

Next steps