@localblok/feature-flags

Client-side feature flags, A/B tests and staged rollouts.

Flags are evaluated in your app, not on our servers. You download a config once and every read after that is a synchronous local computation: no request in your render path, no spinner while a flag resolves, and no outage on our side that can take down your checkout page.

Install

npm install @localblok/feature-flags

Set up

Copy your client key and base URL from Feature Flags → Install in the dashboard. The client key is public — it ships in your bundle, the same as a Firebase web config — and can do exactly two things: read flag configs and report exposure counts.

A client key belongs to one project, so the key alone says which app's flags to serve. If you run several apps, give each its own project and its own key.

import { createFlagsClient } from "@localblok/feature-flags";

export const flags = createFlagsClient({
  clientKey: "fk_live_...",
  baseUrl: "https://your-deployment.convex.site",
  userId: currentUser?.id,
  attributes: { plan: "pro", country: "US" },
});

Read them anywhere:

if (flags.getBoolean("new_checkout", false)) {
  renderNewCheckout();
}

const cta = flags.getString("cta_text", "Buy now");
const limit = flags.getNumber("upload_limit", 10);
const theme = flags.getJson("theme_config", { accent: "blue" });

Every getter takes the default to use when the flag is missing, archived, or we are unreachable. Make it the behaviour you want when the flag system isn't there at all — that is what your users get during an outage.

React

import { FlagsProvider, useBooleanFlag } from "@localblok/feature-flags/react";
import { flags } from "./flags";

function App() {
  return (
    <FlagsProvider client={flags}>
      <Checkout />
    </FlagsProvider>
  );
}

function Checkout() {
  const isNew = useBooleanFlag("new_checkout", false);
  return isNew ? <NewCheckout /> : <LegacyCheckout />;
}

Also exported: useFlag, useStringFlag, useNumberFlag, useJsonFlag, useVariant, useFlagsClient.

Environments

The SDK sends its hostname and the server picks the matching environment, using the host patterns you configured in the dashboard (localhost → Development, and so on). Override it when you need to:

createFlagsClient({ clientKey, baseUrl, environment: "staging" });

Identifying users

Bucketing is a pure function of the user id, so the same person gets the same variants back on every visit without a round trip. Call identify() after sign-in so a visitor's flags follow their account rather than their device:

flags.identify({ userId: user.id, attributes: { plan: user.plan } });

With no userId, the client generates a stable per-device id and stores it. It does that rather than re-rolling per page load because a treatment that flickers in and out is worse than no test at all.

What reaches your users, and when

| | | | --- | --- | | First paint | Last cached config, synchronously. No await needed. | | Config changes | Picked up on the next poll — every 5 minutes by default. | | Kill switch | Same poll interval. Set pollIntervalMs lower if you need it faster. | | We're unreachable | Last cached config; then the defaults in your code. |

await flags.ready() resolves once a config is in hand — from cache, bootstrap or network. It resolves on failure too, with whatever the client has, so it will not hang your boot sequence.

Exposure reporting

The client counts which variant it served and posts those counts on a timer, which is what draws the rollout chart in the dashboard. Counts only — no user ids leave your app. Turn it off with flushIntervalMs: 0.

Options

| Option | Default | | | --- | --- | --- | | clientKey | — | Required. Your fk_... key. | | baseUrl | — | Required. Your .convex.site origin. | | userId | per-device id | The bucketing unit. | | attributes | {} | Targeting attributes. | | environment | auto-detected | Overrides host matching. | | pollIntervalMs | 300000 | 0 disables polling. | | flushIntervalMs | 30000 | 0 disables exposure reporting. | | bootstrap | — | A config payload from SSR, used before the first fetch. |