Flags in git
Keep flag definitions in your repo, reviewed in a pull request. Whether a flag is on, and who it targets, stays with whoever is on call.
export default {
project: { key: "acme", name: "Acme" },
environment: { key: "development", name: "Development" },
flags: [
{
key: "new-checkout",
name: "New checkout flow",
kind: "boolean",
clientAvailable: true,
tags: ["checkout"],
variations: [{ name: "off", value: false }, { name: "on", value: true }],
config: {
enabled: true,
offVariation: "off",
fallthroughRollout: {
variations: [{ variation: "on", weight: 10_000 }, { variation: "off", weight: 90_000 }],
},
targets: [{ variation: "on", keys: ["u-ana", "qa-bot"] }],
},
},
{
key: "promo-banner",
name: "Promo banner",
kind: "string",
variations: [{ name: "none", value: "" }, { name: "sale", value: "Upgrade and save 10%" }],
config: { enabled: false, offVariation: "none", fallthroughVariation: "sale" },
},
],
};
import { FeaturekitServer } from "featurekit-server";
import flags from "./flags.js";
await new FeaturekitServer({ flags }).start();
What happens on start
| The flag… | featurekit… |
|---|---|
| doesn't exist yet | Creates it and applies its config. |
| already exists | Leaves its configuration alone. Name, description, tags and variations are updated from the file. |
exists, with flagsReset: true | Re-applies config, overwriting whatever was changed in the dashboard. |
The project and environment are created if they don't exist. Every change goes through the same
validation as the API and lands in the audit log under a config-as-code actor.
Someone turns a flag off at 3am during an incident. If every boot re-applied the file, the next deploy would turn it back on, at the moment nobody is watching. Definitions are code; operational state is not.
The file
| Field | Notes |
|---|---|
project | { key, name } |
environment | { key, name, isProduction?, color? }. One per file. |
flags[] | Up to 1,000. The same fields as creating a flag, plus config. |
config | The same fields as a configuration change, minus expectedVersion. |
In the file, a variation can be named ("on") instead of indexed (1), anywhere a
variation is expected: offVariation, fallthroughVariation, targets, rules and
rollout slices. Weights are out of 100,000.
Development and production
flags is a development convenience: a fresh checkout and a fresh database give the same flags.
In production start() refuses it, because applying definitions is a deploy step, not
something every booting node should do. Create flags from CI with the
admin API and a scoped
token instead.
flagsReset: true (or FEATUREKIT_FLAGS_RESET=1) re-applies every flag's
config on the next start. Use it to reset a development database, not by default.