Feature flags
A feature flag is an on/off switch an admin flips at
/admin/feature-flags. Every new launchable feature or kill switch goes
behind a flag, not an environment variable. A flag change needs no deploy and
no migration, and it leaves an audit row.
Registry: packages/core/src/server/feature-flags.ts. Router:
packages/core/src/server/trpc/routers/feature-flags.ts. Panel:
apps/web/src/components/admin/FeatureFlagsPanel.tsx.
How a value is decided
Section titled “How a value is decided”flowchart TD
A["isFeatureEnabled(name)"] --> B{"30 s cache fresh?"}
B -->|yes| D
B -->|no| C["read site_settings rows for every flag key"]
C -->|DB error| E["env default, error to Sentry"]
C --> D{"override row for this key?"}
D -->|yes| F["override { enabled }"]
D -->|no| G["defaultEnabled(env)"]
- Values live in
site_settingsas{ enabled: boolean }, keyedfeature_flag.<name>. No row means the env default applies. - Each process caches all flag rows for 30 seconds. After a toggle, the replica that served it sees the change at once. Every other web and API replica sees it within 30 s.
- If the database read fails, the flag falls back to its env default and the error goes to Sentry. So a Neon blip keeps the production petition closed, not open.
The admin panel
Section titled “The admin panel”The Feature flags tab shows, for each flag: the current state; whether that
is the default or an admin override; the default’s source (for example
PETITION_PC_LIVE=1); and who last changed it, and when. Reset to default
deletes the override row. Flags that change something the public sees declare
confirm copy, and the panel asks for confirmation before flipping them.
Writing a flag
Section titled “Writing a flag”Only featureFlags.set writes flags. It is admin/superadmin only and calls
logAudit (resource feature_flag: UPDATE to set, DELETE to reset).
siteSettings.set rejects any feature_flag.* key, so the generic settings
editor cannot bypass the audit.
Current flags
Section titled “Current flags”| Name | Group | Default | What it gates |
|---|---|---|---|
petition_pc |
Campaigns | On outside production, or PETITION_PC_LIVE=1 |
The whole petition: page, verify page, share images, sitemap entry, signing. Off returns a real 404 everywhere |
auction_first_bid_email |
Auctions | AUCTION_FIRST_BID_EMAIL_ENABLED=true |
The one-time welcome email on a user’s first ever auction bid |
signing_package_upgrade |
Tickets | On outside production | Starting signing package upgrades for customers and staff. Off hides upgrade options and rejects apply requests; existing upgrade balances remain payable online and collectable at the counter |
petition_pc replaced the PETITION_PC_LIVE env check, and
auction_first_bid_email replaced a direct env check. Both env vars still work,
but only as the default.
Adding a flag
Section titled “Adding a flag”- Add an entry to
FEATURE_FLAGSwithkey(feature_flag.<name>),label,description,group,defaultEnabled(env),defaultSource, andconfirmcopy if the public will notice the change. - Read it with
await isFeatureEnabled("<name>")on the server. - That is all. The flag appears in the panel automatically.
