/api-flags-posthog-flags

name: api-flags-posthog-flags
description: PostHog feature flags, rollouts, A/B testing. Use when implementing gradual rollouts, A/B tests, kill switches, remote configuration, beta features, or user targeting with PostHog.

Feature Flags with PostHog

> **Quick Guide:** Use PostHog feature flags for gradual rollouts, A/B testing, and remote configuration. Client-side: `useFeatureFlagEnabled` hook. Server-side: `posthog-node` with local evaluation. Always pair `useFeatureFlagPayload` with `useFeatureFlagEnabled` for experiments. Handle the `undefined` loading state on every flag check.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST always pair `useFeatureFlagPayload` with `useFeatureFlagEnabled` or `useFeatureFlagVariantKey` for experiments - payload hooks don't send exposure events)**

**(You MUST use the feature flags secure API key (phs\_\*) for server-side local evaluation - personal API keys are deprecated for this use)**

**(You MUST handle the `undefined` state when flags are loading - never assume a flag is immediately available)**

**(You MUST include flag owner and expiry date in flag metadata - flags without owners become orphaned debt)**

**(You MUST wrap flag usage in a single function when used in multiple places - prevents orphaned flag code on cleanup)**

</critical_requirements>

---

**Auto-detection:** PostHog feature flags, useFeatureFlagEnabled, useFeatureFlagPayload, useFeatureFlagVariantKey, PostHogFeature, isFeatureEnabled, getFeatureFlag, gradual rollout, A/B test, experiment, multivariate flag

**When to use:**

• Gradual rollouts (deploy to 10% users, then 50%, then 100%)
• A/B testing with experiments (measure impact of changes)
• Kill switches (instantly disable features without deploy)
• Remote configuration (change behavior without code changes)
• Beta features opt-in (let users try new features)
• User targeting (show features to specific cohorts)

**When NOT to use:**

• Simple on/off switches that never change (use environment variables)
• Configuration that must be compile-time (use build flags)
• Secrets or sensitive data (use secret management)
• Features that should always be on (just ship the code)

**Key patterns covered:**

• Client-side flag evaluation with React hooks
• Server-side local evaluation for performance
• Boolean vs multivariate flags
• Gradual rollouts with percentage targeting
• A/B testing and experiments
• Payloads for remote configuration
• Local development overrides
• Flag cleanup and lifecycle management

---

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Boolean flags, multivariate flags, PostHogFeature component, payloads, experiments, rollouts, lifecycle management
• [examples/server-side.md](examples/server-side.md) - Server-side evaluation, local evaluation setup, distributed environments
• [examples/development.md](examples/development.md) - Local overrides, bootstrapping, onFeatureFlags callback
• [reference.md](reference.md) - Decision frameworks and anti-patterns

---

<philosophy>

Philosophy

Feature flags decouple deployment from release. You can ship code to production but control who sees it and when. This enables:

1. **Safe releases** - Roll out to 1% first, monitor, then expand 2. **Fast rollback** - Toggle off instantly without deploying 3. **Data-driven decisions** - A/B test to measure impact 4. **Progressive delivery** - Beta users first, then everyone

**Core principles:**

• Flags are temporary - plan for cleanup from day one
• Flags have owners - someone is responsible for each flag
• Simple flags are better - percentage rollouts over complex conditions
• Handle undefined - flags load asynchronously

**When to use feature flags:**

• Risky features that need gradual rollout
• Features requiring A/B testing for validation
• Features that may need instant rollback
• Beta programs with user opt-in

**When NOT to use feature flags:**

• Every feature (creates maintenance burden)
• Permanent configuration (use config files)
• Features that are ready for 100% release

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Client-Side Boolean Flags

Use `useFeatureFlagEnabled` for simple on/off features. Always handle the `undefined` loading state -- treating it as `false` causes a flash of wrong UI.

const isNewCheckout = useFeatureFlagEnabled(FLAG_NEW_CHECKOUT);

if (isNewCheckout === undefined) return <Skeleton />;   // Loading
if (isNewCheckout) return <NewCheckout />;               // Enabled
return <LegacyCheckout />;                               // Disabled

Store flag keys as named constants in `lib/feature-flags.ts` to prevent typos and enable cleanup-by-grep.

See [examples/core.md](examples/core.md#pattern-1-client-side-boolean-flags) for full good/bad examples.

---

Pattern 2: Multivariate Flags and Variants

Use `useFeatureFlagVariantKey` for A/B tests with multiple variants. Define variant constants alongside the flag key. Switch on variants with a default fallback to `control`.

const variant = useFeatureFlagVariantKey(FLAG_PRICING_PAGE);
if (variant === undefined) return <Skeleton />;

switch (variant) {
  case VARIANT_SIMPLE: return <SimplePricing />;
  case VARIANT_DETAILED: return <DetailedPricing />;
  default: return <ControlPricing />;
}

See [examples/core.md](examples/core.md#pattern-2-multivariate-flags-and-variants) for full example.

---

Pattern 3: PostHogFeature Component

The `PostHogFeature` component provides automatic exposure tracking and built-in fallback handling with less boilerplate. Use `match={true}` for boolean flags or `match={VARIANT_KEY}` for specific variants.

<PostHogFeature flag={FLAG_BETA} match={true} fallback={<Legacy />}>
  <NewFeature />
</PostHogFeature>

See [examples/core.md](examp