Feature Flags.instructions

# PostHog Feature Flags

## Overview

Feature flags enable you to toggle features for specific users or cohorts, perform gradual rollouts, run A/B tests, and quickly disable problematic features in production. This project uses PostHog for both client-side and server-side feature flag evaluation.

## When to Use Feature Flags

Use feature flags when you need to:

- ✅ Test new features with a subset of users before full rollout
- ✅ Perform gradual rollouts (canary releases) starting at 5-10% of users
- ✅ Show different UI variations for A/B testing and experiments
- ✅ Gate beta features for specific user groups or email addresses
- ✅ Quickly disable problematic features without deploying code
- ✅ Show/hide features based on user properties (location, plan, etc.)
- ✅ Display one-time popups or announcements
- ✅ Control access to premium features based on subscription status

## Architecture: Client vs Server-Side Evaluation

### Client-Side Feature Flags

**When to use:**

- UI variations and component visibility
- Features that can briefly "flicker" during load
- Non-critical feature toggles
- Simpler implementation with automatic hydration

**How it works:**

1. PostHog loads in browser after hydration
2. Flags evaluated client-side using `posthog.isFeatureEnabled()`
3. React state updates trigger re-render with correct variation

### Server-Side Feature Flags

**When to use:**

- Initial page render requires flag value (prevent flicker)
- SEO-critical content that must be correct on first paint
- Features that affect server-side data fetching
- A/B tests where initial render matters

**How it works:**

1. Flag evaluated in route `loader()` using `posthog-node`
2. Flag value included in loader data
3. Component receives correct value immediately, no flicker

## Implementation Patterns

Use for SEO-critical content or when flicker-free experience is required.

#### Step 1: Evaluate Flag in Loader