How it works
Five nouns, one evaluation order, and two kinds of SDK. That's the whole model.
What featurekit stores
| Thing | What it is |
|---|---|
| Project | Holds flags and segments. Most teams have one. |
| Environment | Development, staging, production. Each has its own configuration for every flag, its own keys and its own snapshot. Marking one isProduction turns on secure mode and production warnings. |
| Flag | A key, a kind (boolean, string, number, json) and 2 to 100 variations, the values it can serve. Shared by every environment. |
| Flag configuration | Per environment: on or off, what to serve when off, targets, rules, prerequisites, and what everyone else gets. Has a version that goes up on every change. |
| Segment | A list of context keys, like "beta testers", that rules can target. |
Contexts
A context is whoever you're asking about: a user, an organization, a device. It has a key and any attributes you want rules to read.
flags.get("new-checkout", { key: "usr_123", plan: "pro", country: "DE" }, false);
A plain object is a user. To target several kinds at once, pass a multi-context. See
targeting rules.
How a flag is evaluated
The same fixed order every time. The first step that answers wins.
| # | Step | Serves | reason |
|---|---|---|---|
| 1 | The flag isn't in the snapshot | Your default | FLAG_NOT_FOUND |
| 2 | The flag is off | The off variation | OFF |
| 3 | A prerequisite isn't met | The off variation | PREREQUISITE_FAILED |
| 4 | The context's key is listed in a target | That target's variation | TARGET_MATCH |
| 5 | A rule matches (first one wins) | The rule's variation or rollout | RULE_MATCH |
| 6 | Nothing matched | The fallthrough variation or rollout | FALLTHROUGH |
Anything that goes wrong (a malformed context, a value of the wrong type) returns your default with
ERROR. Evaluation never throws, and one broken flag never affects another.
Two kinds of SDK
| Server SDK | Client SDK | |
|---|---|---|
| Package | featurekit-server/sdk | featurekit-client |
| Runs in | Your backend (Node) | Browsers, React Native, Deno, Bun, edge |
| Key | fk_srv_…, secret | fk_clt_… or fk_mob_…, public |
| Receives | Every rule, compiled | Evaluated values for one context |
| A check | get(key, context, default), any context, in memory | get(key, default), its one context |
This split is the security boundary. The server routes refuse client keys and the client routes refuse server keys, so a browser can never be handed your rules.
From toggle to your app
-
You change a flag
In the dashboard, the API, the MCP server or the flags file. The configuration, its new version and an audit row are written in one transaction.
-
It compiles into a snapshot
Changes are batched for 200ms, then compiled into a versioned snapshot of the whole environment. A compile that fails leaves the last good snapshot serving.
-
Every SDK hears about it
Server SDKs get a patch over their stream; client SDKs get new values only if theirs changed. Other control-plane nodes are told through Postgres
NOTIFY. The kill switch skips the 200ms wait. -
Your next
get()sees itNo restart, no redeploy, no request on the check itself.
When something breaks
The SDK steps down one level at a time and keeps answering.
| Serving from | When |
|---|---|
| The streamed rules | Normally. |
| The last good snapshot, in memory | The control plane or Postgres is down, or a change won't compile. |
| The snapshot saved to disk | Your app restarted while the control plane was unreachable. Needs persist. |
| Your default | Nothing else is available. That's why the default is required. |