define-feature-flag

# Define a frontend feature flag Frontend only. Registry: `apps/web/src/lib/core/constant/featureFlags.ts`. There is no shared backend flag system. ## 1. Remote or env-only? | | Remote | Env-only | |---|---|---| | Source of truth | PostHog in deployed envs | `default`, optionally overridden by env | | Discriminator | `key` present | no `key` | | `env` | optional local override | optional override of `default` | | `default` | omit / `undefined` to fall through to PostHog | required | | Readers | `useFeatureFlag`, `ShowFeatureFlag`, `isFeatureEnabled` | `isFeatureEnabled` only | Most product rollouts are **remote**. Use **env-only** when there is no PostHog flag and never will be (compile-time / local kill switch). Ask before assuming. If the user said "flag it" and did not mention PostHog, prefer remote and confirm. ## 2. Define it Add one `defineFlag` next to its neighbors. Do not add `ENABLE_*_FLAG` / `_OVERRIDE` / `ENABLE_*()` triples or a raw PostHog string at the call site. - `key` (remote): kebab-case, named after the question (`enable-foo`, `disable-browser-turso-cache`). Export the object in matching camelCase (`enableFoo`). - `env`: the name after `VITE_`, e.g. `'ENABLE_FOO'` → `VITE_ENABLE_FOO`. - `default`: used when env is unset. On a remote flag, `false` is a real override and **skips PostHog**. On-in-dev / on-in-local is `DEV_MODE_ENV || undefined` or `LOCAL_ONLY || undefined`, not the boolean itself. - Never invert on the flag object. If the product question is "disable X", invert at the call site (`!isFeatureEnabled(disableX)`). - Env-only exports that are used as `if (ENABLE_FOO)` must be the boolean: `defineFlag({ env, default }).enabled`. The object is always truthy. ```ts export const enableFoo = defineFlag({ key: 'enable-foo', env: 'ENABLE_FOO', default: DEV_MODE_ENV || undefined, }); export const ENABLE_BAR = defineFlag({ env: 'ENABLE_BAR', default: false, }).enabled; ``` Do not create the PostHog flag. Ask which project / environment it should live in and wait. ## 3. Read it ```ts const foo = useFeatureFlag(enableFoo); // component: foo().enabled <ShowFeatureFlag flag={enableFoo}>{...}</ShowFeatureFlag> isFeatureEnabled(enableFoo) // queries, helpers, env-only ``` A thin `useXFlag` wrapper around `useFeatureFlag(flag)` is fine when several call sites share the same read. Compose flags in the wrapper (calendar search requires calendar UI), not on the flag object. `useFeatureFlag` / `ShowFeatureFlag` take a `RemoteFlag`. Passing an env-only flag is a type error. ## Don't - Migrate existing FLAG / OVERRIDE / string `useFeatureFlag` call sites unless you are already changing that flag or were asked to. - Invent a second helper (`resolveFeatureFlag` for new flags, a global `flags.foo` map, `.use()` / `.Show()` on the object).