Skip to content

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.

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_settings as { enabled: boolean }, keyed feature_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 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.

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.

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.

  1. Add an entry to FEATURE_FLAGS with key (feature_flag.<name>), label, description, group, defaultEnabled(env), defaultSource, and confirm copy if the public will notice the change.
  2. Read it with await isFeatureEnabled("<name>") on the server.
  3. That is all. The flag appears in the panel automatically.