Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

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.md
new file mode 100644
index 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.md
index 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`; keep
feature-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.tsx
index 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 changes
equals: (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.ts
index 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',