fix: feature flag undefined until evaluated

Author: izadoesdev

apps/api/src/routes/public/flags.test.ts

@@ -731,4 +731,114 @@ describe('Flag Evaluation System', () => {
 			expect(totalEnabled).toBeGreaterThan(0);
 		});
 	});
+
+	describe('Comprehensive User Consistency', () => {
+		it('should always return the same result for the same user across 1000 evaluations', () => {
+			const testUserIds = [
+				'user_001',
+				'user_002',
+				'user_003',
+				'user_004',
+				'user_005',
+				'user_006',
+				'user_007',
+				'user_008',
+				'user_009',
+				'user_010',
+			];
+
+			const flags = [
+				{
+					key: 'boolean-flag',
+					type: 'boolean',
+					defaultValue: false,
+					payload: { feature: 'test' },
+					rules: [
+						{
+							type: 'user_id',
+							operator: 'equals',
+							value: 'user_001',
+							enabled: true,
+							batch: false,
+						},
+						{
+							type: 'email',
+							operator: 'ends_with',
+							value: '@test.com',
+							enabled: true,
+							batch: false,
+						},
+					],
+				},
+				{
+					key: 'rollout-flag',
+					type: 'rollout',
+					defaultValue: false,
+					rolloutPercentage: 50,
+					payload: { rollout: true },
+					rules: [],
+				},
+				{
+					key: 'percentage-flag',
+					type: 'boolean',
+					defaultValue: false,
+					payload: { percentage: true },
+					rules: [
+						{
+							type: 'percentage',
+							operator: 'equals',
+							value: 25,
+							enabled: true,
+							batch: false,
+						},
+					],
+				},
+				{
+					key: 'property-flag',
+					type: 'boolean',
+					defaultValue: false,
+					payload: { property: true },
+					rules: [
+						{
+							type: 'property',
+							field: 'plan',
+							operator: 'equals',
+							value: 'premium',
+							enabled: true,
+							batch: false,
+						},
+					],
+				},
+			];
+
+			const contexts: UserContext[] = testUserIds.map((userId) => ({
+				userId,
+				email: `${userId}@test.com`,
+				properties: { plan: userId === 'user_001' ? 'premium' : 'free' },
+			}));
+
+			const baselineResults: Record<string, boolean> = {};
+
+			// First evaluation - establish baseline
+			for (const userId of testUserIds) {
+				for (const flag of flags) {
+					const context = contexts.find((c) => c.userId === userId);
+					const result = evaluateFlag(flag, context);
+					baselineResults[`${userId}-${flag.key}`] = result.enabled;
+				}
+			}
+
+			for (let evaluation = 0; evaluation < 1000; evaluation++) {
+				for (const userId of testUserIds) {
+					for (const flag of flags) {
+						const context = contexts.find((c) => c.userId === userId);
+						const result = evaluateFlag(flag, context);
+						const key = `${userId}-${flag.key}`;
+
+						expect(result.enabled).toBe(baselineResults[key]);
+					}
+				}
+			}
+		});
+	});
 });

apps/dashboard/app/(main)/websites/[id]/_components/website-page-header.tsx

@@ -91,7 +91,7 @@ export function WebsitePageHeader({
 								</Link>
 							</Button>
 						)}
-						<div className="rounded-xl border border-primary/20 bg-primary/10 p-3">
+						<div className="rounded-xl border border-primary/10 bg-primary/5 p-3">
 							{icon}
 						</div>
 					</div>
@@ -105,7 +105,7 @@ export function WebsitePageHeader({
 				<div className="flex items-center gap-3">
 					{onRefresh && (
 						<Button
-							className="gap-2"
+							className="cursor-pointer gap-2 transition-all duration-300 hover:border-primary/50 hover:bg-primary/5"
 							disabled={isRefreshing}
 							onClick={onRefresh}
 							variant="outline"
@@ -137,7 +137,7 @@ export function WebsitePageHeader({
 									</Link>
 								</Button>
 							)}
-							<div className="rounded-xl border border-primary/20 bg-gradient-to-br from-primary/10 to-primary/5 p-3">
+							<div className="rounded-xl border border-primary/10 bg-gradient-to-br from-primary/5 to-primary/10 p-3">
 								{icon}
 							</div>
 							<div>
@@ -151,7 +151,7 @@ export function WebsitePageHeader({
 					<div className="flex items-center gap-3">
 						{onRefresh && (
 							<Button
-								className="gap-2 border-border/50 transition-all duration-200 hover:border-primary/50 hover:bg-primary/5"
+								className="cursor-pointer select-none gap-2 border-border/50"
 								disabled={isRefreshing}
 								onClick={onRefresh}
 								variant="outline"
@@ -165,7 +165,7 @@ export function WebsitePageHeader({
 						)}
 						{onCreateAction && (
 							<Button
-								className="gap-2 bg-gradient-to-r from-primary to-primary/90 shadow-lg transition-all duration-200 hover:from-primary/90 hover:to-primary hover:shadow-xl"
+								className="group relative cursor-pointer select-none gap-2 overflow-hidden bg-gradient-to-r from-primary to-primary/90 px-8 py-4 font-medium text-sm transition-all duration-300 hover:from-primary/90 hover:to-primary"
 								onClick={onCreateAction}
 							>
 								<PlusIcon size={16} />
@@ -181,7 +181,7 @@ export function WebsitePageHeader({
 				<Card className="rounded-xl border-red-200 bg-red-50 dark:border-red-800 dark:bg-red-950">
 					<CardContent className="pt-6">
 						<div className="flex flex-col items-center space-y-3 text-center">
-							<div className="rounded-full border border-destructive/20 bg-destructive/10 p-3">
+							<div className="rounded-full border border-destructive/10 bg-destructive/5 p-3">
 								{icon}
 							</div>
 							<div>
@@ -195,7 +195,7 @@ export function WebsitePageHeader({
 							</div>
 							{onRefresh && (
 								<Button
-									className="gap-2 rounded-lg"
+									className="cursor-pointer select-none gap-2 rounded transition-all duration-300 hover:border-primary/20 hover:bg-primary/10"
 									onClick={onRefresh}
 									size="sm"
 									variant="outline"

apps/dashboard/app/(main)/websites/[id]/flags/page.tsx

@@ -144,19 +144,21 @@ export default function FlagsPage() {
 				websiteId={websiteId}
 				websiteName={website?.name || undefined}
 			/>
-			<div className="flex items-center gap-2">
-				<FlagIcon
-					className="h-5 w-5"
-					color={isExperimentEnabled ? 'red' : 'blue'}
-					size={16}
-					weight="fill"
-				/>
-				{isExperimentEnabled ? (
-					<Badge className="bg-red-500 text-white">Red Team</Badge>
-				) : (
-					<Badge className="bg-blue-500 text-white">Blue Team</Badge>
-				)}
-			</div>
+			{isExperimentEnabled !== undefined && (
+				<div className="flex items-center gap-2">
+					<FlagIcon
+						className="h-5 w-5"
+						color={isExperimentEnabled ? 'red' : 'blue'}
+						size={16}
+						weight="fill"
+					/>
+					{isExperimentEnabled ? (
+						<Badge className="bg-red-500 text-white">Red Team</Badge>
+					) : (
+						<Badge className="bg-blue-500 text-white">Blue Team</Badge>
+					)}
+				</div>
+			)}
 			<Suspense fallback={<FlagsListSkeleton />}>
 				<FlagsList
 					flags={flags || []}

apps/dashboard/components/empty-state.tsx

@@ -60,21 +60,21 @@ export function EmptyState({
 	const renderIcon = () => {
 		if (variant === 'simple' || variant === 'minimal') {
 			return (
-				<div className="mb-4 rounded-full border border-muted bg-muted/20 p-6">
+				<div className="mb-4 rounded-full border border-muted bg-muted/10 p-6">
 					{icon}
 				</div>
 			);
 		}
 
 		return (
 			<div className="group relative mb-8">
-				<div className="rounded-full border-2 border-primary/20 bg-primary/10 p-6">
+				<div className="rounded-full border-2 border-primary/10 bg-primary/5 p-6">
 					{icon}
 				</div>
 				{showPlusBadge && (
 					<div
 						aria-label="Create new item"
-						className="-top-2 -right-2 absolute cursor-pointer rounded-full border-2 border-primary/20 bg-background p-2 shadow-sm"
+						className="-top-2 -right-2 absolute cursor-pointer select-none rounded-full border-2 border-primary/10 bg-background p-2"
 						onClick={(e) => {
 							e.stopPropagation();
 							action?.onClick();
@@ -98,7 +98,7 @@ export function EmptyState({
 	const renderCard = () => {
 		const cardClasses = cn(
 			variant === 'default' &&
-				'rounded-xl border-2 border-dashed bg-gradient-to-br from-background to-muted/20',
+				'rounded-xl border-2 border-dashed bg-gradient-to-br from-background to-muted/10',
 			variant === 'simple' && 'rounded border-dashed bg-muted/10',
 			variant === 'minimal' && 'rounded border-none bg-transparent shadow-none',
 			className
@@ -147,9 +147,11 @@ export function EmptyState({
 									<Button
 										className={cn(
 											variant === 'default' &&
-												'group relative cursor-pointer gap-2 overflow-hidden rounded-lg bg-gradient-to-r from-primary to-primary/90 px-8 py-4 font-medium text-base transition-all duration-300 hover:from-primary/90 hover:to-primary',
-											variant === 'simple' && 'gap-2',
-											variant === 'minimal' && 'gap-2'
+												'group relative cursor-pointer select-none gap-2 overflow-hidden rounded-lg bg-gradient-to-r from-primary to-primary/90 px-8 py-4 font-medium text-base transition-all duration-300 hover:from-primary/90 hover:to-primary',
+											variant === 'simple' &&
+												'cursor-pointer select-none gap-2',
+											variant === 'minimal' &&
+												'cursor-pointer select-none gap-2'
 										)}
 										onClick={action.onClick}
 										size="lg"

apps/docs/content/docs/features/feature-flags.mdx

@@ -57,8 +57,8 @@ function MyComponent() {
 
   return (
     <div className={darkModeEnabled ? 'dark' : ''}>
-      {showNewFeature && <NewDashboard />}
-      {showBetaFeatures && <BetaFeatures />}
+      {showNewFeature !== undefined && showNewFeature && <NewDashboard />}
+      {showBetaFeatures !== undefined && showBetaFeatures && <BetaFeatures />}
       <button>Click me</button>
     </div>
   );
@@ -94,7 +94,7 @@ function MyComponent() {
 
   return (
     <div>
-      {showNewFeature && <NewFeature />}
+      {showNewFeature !== undefined && showNewFeature && <NewFeature />}
       <button>Click me</button>
     </div>
   );
@@ -168,10 +168,15 @@ const showNewUI = isEnabled('new-ui-rollout');`}
   refresh
 } = useFlags();
 
-// Check if flag is enabled
-const showFeature = isEnabled('my-feature');
+// Check if flag is enabled (returns boolean | undefined)
+const showFeature = isEnabled('my-feature'); // undefined if not evaluated yet
 const darkModeDefault = getValue('dark-mode', false);
 
+// Only render when flag is evaluated
+{showFeature !== undefined && (
+  showFeature ? <NewFeature /> : <OldFeature />
+)}
+
 // Refresh all flags
 await fetchAllFlags();`}
 </CodeBlock>
@@ -251,24 +256,19 @@ Enable debug mode to see flag evaluation in the browser console.
 1. **Use `isPending`** with authentication to prevent race conditions
 2. **Pass Custom Properties** for granular targeting and A/B testing
 3. **Enable Debug Mode** during development to monitor flag evaluation
-4. **Handle Flag Changes** gracefully with loading states
+4. **Handle Flag Evaluation States** properly - flags return `undefined` until evaluated
 5. **Update User Context** after profile changes to refresh flag evaluation
 
 <CodeBlock language="tsx">
-{`// Best practice: Handle loading states
+{`// Best practice: Wait for flag evaluation before rendering
 function FeatureComponent() {
   const { isEnabled } = useFlags();
-  const [isLoading, setIsLoading] = useState(true);
-
-  useEffect(() => {
-    // Simulate loading or wait for flags
-    const timer = setTimeout(() => setIsLoading(false), 100);
-    return () => clearTimeout(timer);
-  }, []);
+  const showNewFeature = isEnabled('new-feature');
 
-  if (isLoading) return <Skeleton />;
+  // Don't render until flag is evaluated
+  if (showNewFeature === undefined) return <Skeleton />;
 
-  return isEnabled('new-feature') ? <NewFeature /> : <OldFeature />;
+  return showNewFeature ? <NewFeature /> : <OldFeature />;
 }`}
 </CodeBlock>
 

packages/sdk/src/react/flags-provider.tsx

@@ -352,12 +352,12 @@ export function useFlags() {
 		return fetchFlag(key);
 	};
 
-	const isEnabled = (key: string): boolean => {
+	const isEnabled = (key: string): boolean | undefined => {
 		if (memoryFlags[key]) {
 			return memoryFlags[key].enabled;
 		}
 		getFlag(key);
-		return false;
+		return;
 	};
 
 	const getValue = (key: string, defaultValue = false): boolean => {

packages/sdk/src/react/types.ts

@@ -28,7 +28,7 @@ export interface FlagsConfig {
 }
 
 export interface FlagsContext {
-	isEnabled: (key: string) => boolean;
+	isEnabled: (key: string) => boolean | undefined;
 	getValue: (key: string, defaultValue?: boolean) => boolean;
 	fetchAllFlags: () => Promise<void>;
 	updateUser: (user: FlagsConfig['user']) => void;