feat: better docs for feature flags

Author: izadoesdev

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

@@ -15,7 +15,56 @@ Feature flags allow you to control feature rollouts and conduct A/B testing with
 
 ## Quick Start
 
-<Tabs items={['React/Next.js', 'Setup']}>
+<Tabs items={['React/Next.js with Auth', 'React/Next.js Basic', 'Setup']}>
+
+<Tab>
+<CodeBlock language="tsx" filename="app.tsx">
+{`'use client';
+
+import { FlagsProvider, useFlags } from '@databuddy/sdk/react';
+import { useSession } from '@databuddy/auth/client';
+
+function App() {
+  const { data: session, isPending } = useSession();
+
+  return (
+    <FlagsProvider
+      clientId="your-website-id"
+      apiUrl="https://api.databuddy.cc"
+      isPending={isPending}
+      user={session?.user ? {
+        userId: session.user.id,
+        email: session.user.email,
+        properties: {
+          plan: session.user.plan || 'free',
+          role: session.user.role || 'user',
+          organization: session.user.organizationId,
+          region: 'us-east', // or from user location
+        }
+      } : undefined}
+    >
+      <MyComponent />
+    </FlagsProvider>
+  );
+}
+
+function MyComponent() {
+  const { isEnabled, getValue } = useFlags();
+
+  const showNewFeature = isEnabled('new-dashboard');
+  const showBetaFeatures = isEnabled('beta-features');
+  const darkModeEnabled = getValue('dark-mode-default', false);
+
+  return (
+    <div className={darkModeEnabled ? 'dark' : ''}>
+      {showNewFeature && <NewDashboard />}
+      {showBetaFeatures && <BetaFeatures />}
+      <button>Click me</button>
+    </div>
+  );
+}`}
+</CodeBlock>
+</Tab>
 
 <Tab>
 <CodeBlock language="tsx" filename="app.tsx">
@@ -40,9 +89,9 @@ function App() {
 
 function MyComponent() {
   const { isEnabled } = useFlags();
-  
+
   const showNewFeature = isEnabled('new-feature');
-  
+
   return (
     <div>
       {showNewFeature && <NewFeature />}
@@ -87,9 +136,22 @@ const showNewUI = isEnabled('new-ui-rollout');`}
   apiUrl="https://api.databuddy.cc"
   user={{
     userId: currentUser.id,
-    email: currentUser.email
+    email: currentUser.email,
+    properties: {
+      plan: currentUser.plan || 'free',
+      role: currentUser.role || 'user',
+      organization: currentUser.organizationId,
+      region: currentUser.region || 'us-east',
+      signupDate: currentUser.createdAt,
+      featureUsage: {
+        reportsViewed: currentUser.reportsViewed || 0,
+        dashboardsCreated: currentUser.dashboardsCreated || 0,
+      }
+    }
   }}
+  isPending={isLoadingSession} // from useSession hook
   debug={process.env.NODE_ENV === 'development'}
+  autoFetch={true} // default: true
 >
   <App />
 </FlagsProvider>`}
@@ -98,22 +160,60 @@ const showNewUI = isEnabled('new-ui-rollout');`}
 ## Hook API
 
 <CodeBlock language="tsx">
-{`const { isEnabled, fetchAllFlags, refresh } = useFlags();
+{`const {
+  isEnabled,
+  getValue,
+  fetchAllFlags,
+  updateUser,
+  refresh
+} = useFlags();
 
 // Check if flag is enabled
 const showFeature = isEnabled('my-feature');
+const darkModeDefault = getValue('dark-mode', false);
 
 // Refresh all flags
 await fetchAllFlags();`}
 </CodeBlock>
 
+## Why isPending Matters
+
+The `isPending` prop is crucial for preventing race conditions and ensuring consistent user experiences:
+
+- **Prevents Flash of Incorrect Content**: Without `isPending`, flags might evaluate with stale user data during authentication state changes
+- **Avoids Unnecessary API Calls**: The SDK waits for authentication to complete before making flag requests
+- **Consistent User Experience**: Users won't see feature toggles based on anonymous user data when they're actually logged in
+- **Better Performance**: Reduces redundant flag evaluations during session transitions
+
+<CodeBlock language="tsx">
+{`// ❌ Bad: No isPending - flags evaluate with wrong user context
+<FlagsProvider user={undefined}>
+  <App /> // Shows anonymous features briefly, then switches
+</FlagsProvider>
+
+// ✅ Good: Waits for session before evaluating flags
+<FlagsProvider isPending={isPending} user={session?.user ? {...} : undefined}>
+  <App /> // Shows correct features immediately
+</FlagsProvider>`}
+</CodeBlock>
+
 ## User Targeting
 
 Target specific users or groups from your dashboard:
 
-- **User ID**: Target specific users
-- **Email**: Target by email or domain
-- **Properties**: Target by custom user properties
+- **User ID**: Target specific users by their unique identifier
+- **Email**: Target by email address or domain (e.g., `@company.com`)
+- **Custom Properties**: Target by user attributes like plan tier, role, organization, region, signup date, or feature usage patterns
+
+### Advanced Targeting with Custom Properties
+
+Custom properties enable sophisticated targeting strategies:
+
+- **Plan-based Rollouts**: `plan: 'premium'` → Show premium features only to paying users
+- **Geographic Targeting**: `region: 'us-east'` → Test features in specific regions
+- **Behavioral Targeting**: `featureUsage.reportsViewed > 10` → Target power users
+- **A/B Testing**: `experimentGroup: 'A'` → Segment users for experiments
+- **Time-based**: `signupDate > '2024-01-01'` → Target new vs. existing users
 
 <CodeBlock language="tsx">
 {`<FlagsProvider
@@ -139,6 +239,39 @@ Target specific users or groups from your dashboard:
 
 Enable debug mode to see flag evaluation in the browser console.
 
+## Performance Benefits
+
+- **Client-side Caching**: Flags are cached in IndexedDB and localStorage for instant loading
+- **Intelligent Updates**: Only re-evaluates flags when user context changes
+- **Background Sync**: Fetches flag updates without blocking the UI
+- **Minimal Bundle Size**: Lightweight SDK with zero external dependencies
+
+## Best Practices
+
+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
+5. **Update User Context** after profile changes to refresh flag evaluation
+
+<CodeBlock language="tsx">
+{`// Best practice: Handle loading states
+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);
+  }, []);
+
+  if (isLoading) return <Skeleton />;
+
+  return isEnabled('new-feature') ? <NewFeature /> : <OldFeature />;
+}`}
+</CodeBlock>
+
 ---
 
 Ready to get started? [Create your first feature flag in the dashboard →](https://app.databuddy.cc/login)