---

name: add-feature-flag description: Add PostHog feature flags for gradual rollouts, A/B tests, or beta features. Use when implementing feature toggles, experiments, or canary releases.

Add Feature Flag

When to Use

• Gradual feature rollouts (canary releases)
• A/B testing and experiments
• Beta feature gating
• Quick feature kill switches

Server vs Client

Server-Side (Flicker-Free)

Copyimport type { Route } from './+types/product-page';
import { isFeatureEnabled } from '~/lib/posthog.server';

export async function loader({ request }: Route.LoaderArgs) {
    const showNewLayout = await isFeatureEnabled('new-product-layout', request);

    return {
        featureFlags: { showNewLayout },
    };
}

Copyexport default function ProductPage({ loaderData }: Route.ComponentProps) {
    const { featureFlags } = loaderData;

    return featureFlags.showNewLayout ? <NewLayout /> : <LegacyLayout />;
}

Client-Side (Simpler)

Copyimport { usePostHog } from 'posthog-js/react';
import { useEffect, useState } from 'react';

export default function FeatureComponent() {
    const posthog = usePostHog();
    const [showFeature, setShowFeature] = useState(false);

    useEffect(() => {
        if (posthog) {
            setShowFeature(posthog.isFeatureEnabled('new-feature') ?? false);
        }
    }, [posthog]);

    return showFeature ? <NewFeature /> : <LegacyFeature />;
}

Naming

Copy// Good
'new-checkout-flow'
'ai-assistant-beta'

// Bad
'flag-123'
'test'

Checklist

1. Choose server or client-side based on requirements
2. Use descriptive flag name
3. Add TODO comment for cleanup date
4. Track conversion events if A/B testing

Full Reference

See .github/instructions/feature-flags.instructions.md for:

• A/B testing with variants
• Gradual rollout strategy
• Debug locally
• Tracking conversion events