Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
feat(web): better feature flag definition and use interface (#6102)
dev-rb87e50c2f8367
diff --git a/.claude/skills/define-feature-flag/SKILL.md b/.claude/skills/define-feature-flag/SKILL.mdnew file mode 100644index 0000000000..295feab299--- /dev/null+++ b/.claude/skills/define-feature-flag/SKILL.md@@ -0,0 +1,81 @@+---+name: define-feature-flag+description: Define a frontend feature flag with `defineFlag` and wire its readers. Use when adding, suggesting, or changing a feature flag, PostHog flag, `ENABLE_*` env flag, `useFeatureFlag`, `isFeatureEnabled`, or `ShowFeatureFlag`.+---++# 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).diff --git a/apps/web/AGENTS.md b/apps/web/AGENTS.mdindex a524aad47d..c4f5677c0e 100644--- a/apps/web/AGENTS.md+++ b/apps/web/AGENTS.md@@ -51,6 +51,7 @@ Then trigger the interaction and read `window.__inst.log`. `'1,2,3' → '' → '- All API/network calls live in service-clients.- Shared server-state queries and mutations live in `src/lib/queries`; keepfeature-specific query orchestration with its owning feature.+- When adding or changing a feature flag, follow the `define-feature-flag` skill.### SolidJs- Avoid createEffect. Legitimate uses: syncing with external/imperative systems (DOM APIs, third-party libs). If you're using it to derive state or trigger updates, use a derived signal or wrap the setter instead.diff --git a/apps/web/src/lib/analytics/posthog.tsx b/apps/web/src/lib/analytics/posthog.tsxindex 83fcaf921e..f7bc9de27e 100644--- a/apps/web/src/lib/analytics/posthog.tsx+++ b/apps/web/src/lib/analytics/posthog.tsx@@ -1,4 +1,5 @@import { useAnalytics } from '@app/lib/analytics/analytics-context';+import type { RemoteFlag } from '@core/constant/featureFlags';import { createAssertedContextProvider } from '@core/context/createContext';import type { JsonType } from 'posthog-js';import {@@ -38,53 +39,92 @@ export const [PosthogProvider, usePosthog] = createAssertedContextProvider(});-type FeatureFlagResult<T> = { enabled: boolean; payload: T };+type FeatureFlagResult<T> = {+ enabled: boolean;+ payload: T;+ loading: boolean;+};-export function useFeatureFlag<T extends JsonType>(- key: string,- opts?: {- fallbackPayload?: T;- enabledOverride?: boolean;- }+type FeatureFlagOpts<T> = {+ fallbackPayload?: T;+ enabledOverride?: boolean;+};++function readFeatureFlag<T extends JsonType>(+ flagOrKey: RemoteFlag | string,+ opts?: FeatureFlagOpts<T>): Accessor<FeatureFlagResult<T | undefined>> {const posthog = usePosthog();return createMemo(() => {- const { enabledOverride, fallbackPayload } = opts ?? {};+ const fallbackPayload = opts?.fallbackPayload;+ const remote = typeof flagOrKey === 'string' ? undefined : flagOrKey;+ const key = typeof flagOrKey === 'string' ? flagOrKey : flagOrKey.key;+ const override = remote?.override ?? opts?.enabledOverride;- if (!posthog.featureFlags().length && !enabledOverride) {- return { enabled: false, payload: fallbackPayload };+ if (override !== undefined) {+ return { enabled: override, payload: fallbackPayload, loading: false };}- const flag = posthog.instance.getFeatureFlagResult(key);+ if (!posthog.flagsLoaded()) {+ return { enabled: false, payload: fallbackPayload, loading: true };+ }- // A defined override wins in both directions: an explicit `false`- // disables even when PostHog reports the flag on.- const enabled = enabledOverride ?? flag?.enabled ?? false;- const payload = (flag?.payload as T) ?? fallbackPayload;+ const result = posthog.instance.getFeatureFlagResult(key);- return { enabled, payload };+ return {+ enabled: result?.enabled ?? false,+ payload: (result?.payload as T) ?? fallbackPayload,+ loading: false,+ };},undefined,{- // Only notify dependents when enabled or payload actually changesequals: (prev, next) =>- prev.enabled === next.enabled && prev.payload === next.payload,+ prev.enabled === next.enabled &&+ prev.payload === next.payload &&+ prev.loading === next.loading,});}-export const ShowFeatureFlag = <T extends JsonType>(props: {- key: string;+export function useFeatureFlag<T extends JsonType>(+ flag: RemoteFlag,+ opts?: { fallbackPayload?: T }+): Accessor<FeatureFlagResult<T | undefined>>;+export function useFeatureFlag<T extends JsonType>(+ key: string,+ opts?: FeatureFlagOpts<T>+): Accessor<FeatureFlagResult<T | undefined>>;+export function useFeatureFlag<T extends JsonType>(+ flagOrKey: RemoteFlag | string,+ opts?: FeatureFlagOpts<T>+): Accessor<FeatureFlagResult<T | undefined>> {+ return readFeatureFlag(flagOrKey, opts);+}++type ShowFeatureFlagProps<T> = {fallback?: JSX.Element;fallbackPayload?: T;- enabledOverride?: boolean;children: JSX.Element;-}) => {- const flag = useFeatureFlag(props.key, {+} & ({ flag: RemoteFlag } | { key: string; enabledOverride?: boolean });++function showFlagTarget<T>(+ props: ShowFeatureFlagProps<T>+): RemoteFlag | string {+ if ('flag' in props) {+ return props.flag;+ }+ return props.key;+}++export const ShowFeatureFlag = <T extends JsonType>(+ props: ShowFeatureFlagProps<T>+) => {+ const flag = readFeatureFlag(showFlagTarget(props), {fallbackPayload: props.fallbackPayload,- enabledOverride: props.enabledOverride,+ enabledOverride: 'flag' in props ? undefined : props.enabledOverride,});return (diff --git a/apps/web/src/lib/core/constant/featureFlags.ts b/apps/web/src/lib/core/constant/featureFlags.tsindex c1527b04d2..58aee37518 100644--- a/apps/web/src/lib/core/constant/featureFlags.ts+++ b/apps/web/src/lib/core/constant/featureFlags.ts@@ -11,25 +11,15 @@ import { analytics } from '@app/lib/analytics';*/export const LOCAL_ONLY = !!import.meta.hot;-type FeatureFlagValue = 'true' | 'false' | undefined;+const parseBooleanOverride = (value: unknown): boolean | undefined =>+ value === 'true' ? true : value === 'false' ? false : undefined;/*** Reads a `VITE_<flagName>` env override. Returns `undefined` when unset, so* callers can fall through to PostHog rather than forcing the flag off.*/export function getFeatureFlagOverride(flagName: string): boolean | undefined {- const envKey = `VITE_${flagName}` as const;- const value = import.meta.env[envKey] as FeatureFlagValue;-- if (value === 'true') {- return true;- }-- if (value === 'false') {- return false;- }-- return undefined;+ return parseBooleanOverride(import.meta.env[`VITE_${flagName}`]);}export function resolveFeatureFlag(@@ -46,6 +36,75 @@ export function resolveFeatureFlag(*/export const DEV_MODE_ENV = import.meta.env.MODE === 'development';+type EnvFlagConfig = {+ key?: never;+ env?: string;+ default: boolean;+};++type RemoteFlagConfig = {+ key: string;+ env?: string;+ default?: boolean;+};++/** Compile-time / env-only flag. Read with `isFeatureEnabled`. */+export type EnvFlag = {+ enabled: boolean;+};++/** PostHog-backed flag. Read with `useFeatureFlag` or `isFeatureEnabled`. */+export type RemoteFlag = {+ key: string;+ override: boolean | undefined;+};++export type Flag = EnvFlag | RemoteFlag;++function envOverride(env: string | undefined): boolean | undefined {+ return env === undefined ? undefined : getFeatureFlagOverride(env);+}++/**+ * Define a feature flag. Pass `key` for PostHog, or `default` (and no `key`)+ * for env-only. `env` is the name after `VITE_`, e.g. `'ENABLE_REMINDERS'`.+ *+ * `default` is used when env is unset. For remote flags, omit it (or pass+ * `undefined`) to defer to PostHog. The caller decides when that default+ * applies, e.g. `DEV_MODE_ENV || undefined` or `LOCAL_ONLY || undefined`.+ *+ * Remote: `useFeatureFlag(flag)` or `isFeatureEnabled(flag)`.+ * Env-only: `isFeatureEnabled(flag)` only.+ */+export function defineFlag(config: RemoteFlagConfig): RemoteFlag;+export function defineFlag(config: EnvFlagConfig): EnvFlag;+export function defineFlag(config: RemoteFlagConfig | EnvFlagConfig): Flag {+ if (config.key !== undefined) {+ return {+ key: config.key,+ override: envOverride(config.env) ?? config.default,+ };+ }++ return {+ enabled: envOverride(config.env) ?? config.default,+ };+}++/**+ * Imperative snapshot. Env/`default` override wins. Otherwise PostHog,+ * or `false` if flags have not loaded or the key is unknown.+ */+export function isFeatureEnabled(flag: Flag): boolean {+ if ('key' in flag) {+ if (flag.override !== undefined) {+ return flag.override;+ }+ return analytics.posthog.isFeatureEnabled(flag.key) ?? false;+ }+ return flag.enabled;+}+/*** Switches Inbox, Tasks, and Channels from the current SoupView implementations* to the new composable view implementations. Override locally with@@ -532,9 +591,6 @@ export const ENABLE_GRAPHQL_SOUP_OVERRIDE = getFeatureFlagOverride('ENABLE_GRAPHQL_SOUP');-const parseBooleanOverride = (value: unknown): boolean | undefined =>- value === 'true' ? true : value === 'false' ? false : undefined;-/** Controls the cache-warming GraphQL soup backfill. */export const ENABLE_GRAPHQL_BACKFILL = resolveFeatureFlag('ENABLE_GRAPHQL_BACKFILL',