Feature flags

Feature flags live in packages/domain/src/feature-flags. A flag has a registry definition, an optional environment default, and optional per-organization overrides.

Resolution order

For a given organization, the first matching source wins:

1. Kill switch — FEATURE_FLAGS_DISABLED="true" disables every flag.
2. Organization override — a row in feature_flag_overrides.
3. Environment default — an entry in FEATURE_FLAGS.
4. Registry default — the flag's built-in default.

Rollouts are bucketed by organizationId with a stable hash, so the admin and storefront agree for the same organization.

Registry

Environment defaults

FEATURE_FLAGS='{"orderSms":{"enabled":true,"rolloutPercentage":100}}'
FEATURE_FLAGS_DISABLED="false"

• Keys must exist in the registry.
• rolloutPercentage is an integer from 0 to 100.
• Malformed JSON fails closed in the apps: the configuration is ignored and the error is logged. The CLI surfaces the parse error directly.

Per-organization overrides

Use the developer CLI from the repository root:

pnpm flags -- list --org my-store
pnpm flags -- set --org my-store --flag orderSms --enabled --rollout 100
pnpm flags -- set --org my-store --flag orderSms --disabled
pnpm flags -- unset --org my-store --flag orderSms
pnpm flags -- unset --org my-store --all

The CLI validates the organization, flag key, and rollout range. It requires Bun and a reachable database.

Adding a flag

1. Add the definition to featureFlagRegistry with a default and description.
2. Use the flag in the app through the feature-flag provider or server helper.
3. Add env defaults if needed.
4. Add tests for resolution and rollout behavior.
5. Document the flag here.
6. Remove the flag when the feature is fully rolled out.

Using flags in the apps

• The admin and storefront expose resolved flag values to the UI through their feature-flag providers.
• Server code can resolve states with resolveFeatureFlagStates and read the boolean values with toFeatureFlagValues.
• Always pass an organization ID; there is no global value without a tenant.

Debugging

• Run pnpm flags -- list --org <slug> to see the resolved state and source.
• Check FEATURE_FLAGS_DISABLED first.
• Check the override row before changing env defaults.
• Remember that a rollout percentage below 100 may exclude the organization you are testing.

Related

• Environment variables
• Architecture