Feature Flags — Integration Guide

import { useFeatureFlag } from '@/platform/feature-flags';

function useFeatureFlag(flagKey: string): {
  enabled: boolean;       // Whether the flag is on for the current user/org
  variant: string | null; // A/B test variant key, or null for boolean/percentage flags
  isLoading: boolean;
  error: Error | null;
};

import { useFeatureFlag } from '@/platform/feature-flags';

function MyComponent() {
  const { enabled } = useFeatureFlag('cl.new_chart_layout');

  if (!enabled) return <LegacyChart />;
  return <NewChart />;
}

const { enabled } = useFeatureFlag('pf.progressive_sidebar');
// `enabled` is true for the configured percentage of users
// Evaluation is deterministic per user — same user always gets the same result

const { enabled, variant } = useFeatureFlag('ce.onboarding_experiment');

if (!enabled) return <DefaultOnboarding />;

switch (variant) {
  case 'streamlined':
    return <StreamlinedOnboarding />;
  case 'guided':
    return <GuidedOnboarding />;
  default:
    return <DefaultOnboarding />;
}

pf_check_feature_flag(
  p_flag_key      TEXT,
  p_user_id       UUID DEFAULT NULL,
  p_organization_id UUID DEFAULT NULL
) RETURNS JSONB

{ "enabled": true, "variant": "streamlined" }

{ "enabled": false, "variant": null }

import { createClient } from 'npm:@supabase/supabase-js@2';

// Security: Verify request JWT, extract userId/orgId server-side
// Enforce admin/RBAC checks or use row-level security
// Only use service role in trusted backend contexts
const supabase = createClient(
  Deno.env.get('SUPABASE_URL')!,
  Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!,
);

const { data, error } = await supabase.rpc('pf_check_feature_flag', {
  p_flag_key: 'fa.new_invoice_format',
  p_user_id: userId,
  p_organization_id: orgId,
});

if (error || !data?.enabled) {
  // Fall back to existing behavior
}

{core}.{feature_name}

// ❌ WRONG: Querying pf_feature_flags directly
const { data } = await supabase
  .from('pf_feature_flags')
  .select('is_enabled')
  .eq('flag_key', 'cl.my_flag');

// ✅ CORRECT: Use the hook or RPC
const { enabled } = useFeatureFlag('cl.my_flag');

// ❌ WRONG: Redundant cache — the hook already caches via TanStack Query
const cached = localStorage.getItem('flag_cl.my_flag');

// ✅ CORRECT: Just use the hook; it handles stale/gc times
const { enabled } = useFeatureFlag('cl.my_flag');

// ❌ WRONG: Hardcoded boolean instead of flag
const ENABLE_NEW_FEATURE = true;

// ✅ CORRECT: Use a flag so it can be toggled without a deploy
const { enabled } = useFeatureFlag('hr.new_feature');

// ❌ WRONG: No loading guard — will flash default then switch
return enabled ? <NewUI /> : <OldUI />;

// ✅ CORRECT: Show skeleton while flag is resolving
if (isLoading) return <Skeleton className="h-48 w-full" />;
return enabled ? <NewUI /> : <OldUI />;