npm - flagmint-react-sdk - Versions diffs - 0.7.13 → 0.7.14 - Mend

flagmint-react-sdk 0.7.13 → 0.7.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/README.md CHANGED Viewed

@@ -4,60 +4,54 @@ A React wrapper for [flagmint-js-sdk](https://www.npmjs.com/package/flagmint-js-
 ## ✨ Features
-- 🎯 **Fine-grained reactivity** - Only components using specific flags re-render when those flags change
+- 🎯 **Fine-grained reactivity** - Only components using a specific flag re-render when that flag changes
 - 🚀 **SSR-safe** - No global state leakage between server requests
 - 📦 **TypeScript support** - Full type safety with generics for flag values and context
-- 🔀 **Dual export strategy** - Separate server-safe types and client-only hooks
-- ⚡ **Auto-initialization** - Direct integration with FlagClient from flagmint-js-sdk
-- 🔐 **Deferred initialization** - Perfect for authentication flows
-- 📱 **Framework agnostic** - Works with Next.js, Remix, Vite, and more
+- ⚡ **Real-time updates** - WebSocket transport keeps flags in sync without polling
+- 🔄 **Offline cache** - Cached flags served instantly on load, even before the server responds
+- 🔁 **Auto fallback** - Falls back to long-polling if WebSocket is unavailable
+- 🔐 **Deferred initialization** - Safe to use in authenticated routes without blocking public pages
 ## 📦 Installation
 ```bash
-npm install react-flagmint flagmint-js-sdk
+npm install flagmint-react-sdk flagmint-js-sdk
 # or
-pnpm add react-flagmint flagmint-js-sdk
+yarn add flagmint-react-sdk flagmint-js-sdk
 # or
-yarn add react-flagmint flagmint-js-sdk
+pnpm add flagmint-react-sdk flagmint-js-sdk
 ```
 ## 🚀 Quick Start
-### 1. Basic Setup
+### 1. Add the Provider to Your Root Layout
+The provider must live as high as possible in your component tree - ideally in your root layout. This ensures the WebSocket connection is created once and persists across route changes.
 ```tsx
-// app/providers.tsx (Next.js App Router)
-'use client'
-import { FlagmintProvider } from 'react-flagmint/client'
+// app/providers.tsx
+'use client';
+import { FlagmintProvider } from 'flagmint-react-sdk/client';
-export default function Providers({ children }: { children: React.ReactNode }) {
+export function Providers({ children }: { children: React.ReactNode }) {
   return (
-    <FlagmintProvider
+    <FlagmintProvider
       options={{
         apiKey: process.env.NEXT_PUBLIC_FLAGMINT_API_KEY!,
         transportMode: 'websocket',
-        context: {
-          userId: 'user-123',
-          plan: 'premium'
-        }
       }}
     >
       {children}
     </FlagmintProvider>
-  )
+  );
 }
 ```
 ```tsx
 // app/layout.tsx
-import Providers from './providers'
+import { Providers } from './providers';
-export default function RootLayout({
-  children,
-}: {
-  children: React.ReactNode
-}) {
+export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
     <html>
       <body>
@@ -66,43 +60,104 @@ export default function RootLayout({
         </Providers>
       </body>
     </html>
-  )
+  );
 }
 ```
+> ⚠️ **Important:** Do not place `FlagmintProvider` inside a nested layout or page component. Doing so causes a new WebSocket connection to be created on every route navigation.
 ### 2. Using Flags in Components
 ```tsx
 // components/FeatureComponent.tsx
-'use client'
-import { useFlag, useFlags, useFlagmintReady } from 'react-flagmint/client'
+'use client';
+import { useFlag, useFlagmintReady } from 'flagmint-react-sdk/client';
 export default function FeatureComponent() {
-  const showNewFeature = useFlag('new-dashboard', false)
-  const userPlan = useFlag('user-plan', 'free')
-  const isReady = useFlagmintReady()
+  const isReady = useFlagmintReady();
+  const showNewDashboard = useFlag<boolean>('new_dashboard', false);
+  const resultsPerPage = useFlag<number>('results_per_page', 10);
+  const colorScheme = useFlag<string>('color_scheme', 'light');
   if (!isReady) {
-    return <div>Loading flags...</div>
+    return <div>Loading...</div>;
   }
   return (
-    <div>
-      {showNewFeature && <NewDashboard />}
-      <div>Current plan: {userPlan}</div>
+    <div className={colorScheme}>
+      {showNewDashboard && <NewDashboard />}
+      <ResultsList limit={resultsPerPage} />
     </div>
-  )
+  );
 }
 ```
+---
+## 🔐 Authentication Flows
+In most apps, flags need user context (user ID, plan, org) that isn't available until after login. The recommended approach is to **always render children** and skip the SDK until the user is authenticated:
+```tsx
+// app/FlagmintProviderSDK.tsx
+'use client';
+import { FlagmintProvider } from 'flagmint-react-sdk/client';
+import { useUser } from '@/hooks/useUser';
+import { useBillingData } from '@/hooks/useBillingData';
+export default function FlagmintProviderSDK({ children }: { children: React.ReactNode }) {
+  const profile = useUser().profile;
+  const { data: billingData, isLoading } = useBillingData(profile?.org_id);
+  const apiKey = process.env.NEXT_PUBLIC_FLAGMINT_API_KEY;
+  // No API key - skip SDK entirely
+  if (!apiKey) return <>{children}</>;
+  // Not logged in or still loading - render children without flags
+  // Public routes (/login, /signup) work fine without flags
+  if (!profile || isLoading) return <>{children}</>;
+  const context = {
+    kind: 'multi',
+    user: { kind: 'user', key: profile.id, email: profile.email },
+    organization: {
+      kind: 'organization',
+      key: profile.org_id,
+      plan: billingData?.currentPlan?.name,
+    },
+  };
+  return (
+    <FlagmintProvider
+      options={{
+        apiKey,
+        transportMode: 'auto',
+        context,
+        onError: (error) => console.error('Flagmint error:', error),
+      }}
+    >
+      {children}
+    </FlagmintProvider>
+  );
+}
+```
+This pattern means:
+- `/login`, `/signup` - children render immediately, no spinner
+- Authenticated pages - provider mounts once with full user context
+- Route navigation - same WebSocket connection, no reconnects
+---
 ## 📚 API Reference
-### FlagmintProvider
+### `FlagmintProvider`
-The provider component that initializes the FlagClient and provides flag context to your app.
+Initializes the `FlagClient` and provides flag context to all children.
 ```tsx
-<FlagmintProvider
+<FlagmintProvider
   options={FlagClientOptions}
   initialFlags={{}}
   deferInitialization={false}
@@ -116,357 +171,249 @@ The provider component that initializes the FlagClient and provides flag context
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `options` | `FlagClientOptions` | Required | Configuration for the FlagClient |
-| `initialFlags` | `Flags` | `{}` | Initial flag values for SSR/hydration |
-| `deferInitialization` | `boolean` | `false` | If true, wait for manual initialization |
+| `initialFlags` | `Flags` | `{}` | Initial flag values for SSR hydration |
+| `deferInitialization` | `boolean` | `false` | If true, skip auto-initialization on mount |
-#### FlagClientOptions
+#### `FlagClientOptions`
-```tsx
+```typescript
 interface FlagClientOptions<C extends Record<string, any> = Record<string, any>> {
-  apiKey: string
-  context?: C
-  transportMode?: 'auto' | 'websocket' | 'long-polling'
-  enableOfflineCache?: boolean
-  persistContext?: boolean
-  onError?: (error: Error) => void
-  previewMode?: boolean
-  rawFlags?: Record<string, FlagValue>
-  deferInitialization?: boolean
+  apiKey: string;                          // Your Flagmint API key
+  context?: C;                             // Evaluation context (user, org, etc.)
+  transportMode?: 'auto' | 'websocket' | 'long-polling'; // Default: 'auto'
+  enableOfflineCache?: boolean;            // Cache flags in localStorage. Default: true
+  persistContext?: boolean;                // Persist context across sessions. Default: false
+  onError?: (error: Error) => void;        // Error handler
+  previewMode?: boolean;                   // Evaluate flags locally from rawFlags
+  rawFlags?: Record<string, FlagValue>;    // Used with previewMode
+  deferInitialization?: boolean;           // Skip initialization until ready() is called
 }
 ```
+**Transport modes:**
+- `'websocket'` - Real-time updates via WebSocket. Best for production.
+- `'long-polling'` - Periodic HTTP polling. Use for environments that don't support WebSocket.
+- `'auto'` - Tries WebSocket first, falls back to long-polling automatically.
+---
 ### Hooks
-#### useFlag(key, fallback?)
+#### `useFlag(key, fallback?)`
-Get a specific flag value with fine-grained reactivity.
+The primary hook for reading a single feature flag. **Only this component re-renders** when this specific flag changes - not when other flags update.
+Returns `fallback` silently if called outside a `FlagmintProvider`, making it safe to use on public pages before the user is authenticated.
 ```tsx
-const showFeature = useFlag('feature-name', false)
-const userTier = useFlag('user-tier', 'free')
-const config = useFlag('app-config', { theme: 'light' })
+const showFeature = useFlag<boolean>('show_documentation_feature', false);
+const plan = useFlag<string>('color_scheme', 'light');
+const limit = useFlag<number>('results_per_page', 10);
+const config = useFlag<{ logging: boolean }>('advanced_settings', { logging: false });
 ```
-**Parameters:**
-- `key: string` - The flag key
-- `fallback?: T` - Default value if flag is not found
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `key` | `string` | The feature flag key |
+| `fallback` | `T` | Value returned when flag is missing or provider not ready |
+---
+#### `useFlags()`
-**Returns:** The flag value or fallback
+Returns all evaluated flags as a reactive object. Re-renders when **any** flag changes.
-#### useFlags()
+Prefer `useFlag` for single flags - `useFlags` is best when you need to pass many flags to a child component at once.
-Get all currently loaded flags.
+Returns `{}` silently if called outside a `FlagmintProvider`.
 ```tsx
-const allFlags = useFlags()
-console.log(allFlags) // { 'feature-a': true, 'user-tier': 'pro' }
+const flags = useFlags();
+// { new_dashboard: true, color_scheme: 'dark', results_per_page: 30 }
 ```
-**Returns:** Object containing all loaded flags
-#### useFlagmint()
+---
-Get access to the FlagClient instance and utilities.
+#### `useFlagmint()`
-```tsx
-const { client, isReady, isInitialized, updateContext } = useFlagmint()
+Provides access to the underlying `FlagClient` and the ability to update the evaluation context. Use this when the user's context changes after initial load (plan upgrade, org switch, login).
-// Update user context
-await updateContext({ userId: 'new-user', plan: 'enterprise' })
-```
+Throws if called outside a `FlagmintProvider`.
-**Returns:**
 ```tsx
-{
-  client: FlagClient | null
-  isReady: boolean
-  isInitialized: boolean
-  updateContext: (context: Record<string, any>) => Promise<void>
-}
+const { client, isInitialized, updateContext } = useFlagmint();
+// Update context after user upgrades plan
+await updateContext({
+  userId: user.id,
+  plan: 'enterprise',
+  orgId: user.orgId,
+});
 ```
-#### useFlagmintReady()
+| Return | Type | Description |
+|--------|------|-------------|
+| `client` | `FlagClient \| null` | The underlying SDK client instance |
+| `isInitialized` | `boolean` | Whether the client has finished initializing |
+| `updateContext` | `(context) => Promise<void>` | Update evaluation context and re-fetch flags |
-Check if the FlagClient is ready to serve flags.
-```tsx
-const isReady = useFlagmintReady()
+---
-if (!isReady) {
-  return <LoadingSpinner />
-}
-```
+#### `useFlagmintReady()`
-#### useFlagClient()
+Returns `true` when the client has finished initializing and flags have been fetched from the server. Use this to prevent a flash of incorrect content on first load.
-Get direct access to the FlagClient instance.
+Returns `false` silently if called outside a `FlagmintProvider`.
 ```tsx
-const client = useFlagClient<MyFlagTypes>()
-const specificFlag = client?.getFlag('feature-x', false)
+const isReady = useFlagmintReady();
+if (!isReady) return <Skeleton />;
+return showNewPricing ? <NewPricing /> : <OldPricing />;
 ```
-## 🔧 Usage Patterns
+---
+#### `useFlagmintStore()` *(Advanced)*
-### 1. Auto-initialization (Default)
+Low-level hook that returns the raw Zustand store. **Use this only when building custom hooks on top of the SDK.** For normal flag consumption always use `useFlag`.
-Best when user context is available immediately:
+Throws immediately if called outside a `FlagmintProvider` - this is intentional, as it helps catch incorrect usage during development.
 ```tsx
-function App() {
-  return (
-    <FlagmintProvider
-      options={{
-        apiKey: 'your-api-key',
-        context: {
-          userId: getCurrentUser().id,
-          plan: getCurrentUser().plan
-        }
-      }}
-    >
-      <Dashboard />
-    </FlagmintProvider>
-  )
+// Building a custom hook that combines multiple flags
+function useCanAccessBeta() {
+  const store = useFlagmintStore();
+  return useStore(store, (state) =>
+    state.flags['beta_access'] && state.flags['new_ui']
+  );
 }
 ```
-### 2. Deferred Initialization
+---
-Perfect for authentication flows:
+### Hook Reference Summary
-```tsx
-// Provider with deferred initialization
-<FlagmintProvider
-  options={{
-    apiKey: 'your-api-key',
-    context: {} // Empty initially
-  }}
-  deferInitialization={true}
->
-  <App />
-</FlagmintProvider>
+| Hook | Use When | Outside Provider |
+|------|----------|-----------------|
+| `useFlag(key, fallback)` | Reading a single flag in any component | Returns `fallback` silently |
+| `useFlags()` | Reading multiple flags at once | Returns `{}` silently |
+| `useFlagmint()` | Updating context after login/upgrade | Throws |
+| `useFlagmintReady()` | Gating renders until flags are loaded | Returns `false` silently |
+| `useFlagmintStore()` | Building custom hooks on top of the SDK | Throws |
-// Login component
-function LoginPage() {
-  const { updateContext } = useFlagmint()
-  const handleLogin = async (user) => {
-    // First update context with user info
-    await updateContext({
-      userId: user.id,
-      plan: user.plan,
-      locale: user.locale
-    })
-    // Flags are now available with user context
-    navigate('/dashboard')
-  }
-  return <LoginForm onLogin={handleLogin} />
-}
-```
+---
-### 3. TypeScript Usage
+## 🔧 Usage Patterns
-Define your flag types for better type safety:
+### TypeScript: Typed Flags
 ```tsx
 // types/flags.ts
 export interface AppFlags {
-  'show-beta-feature': boolean
-  'user-plan': 'free' | 'pro' | 'enterprise'
-  'theme-config': {
-    primaryColor: string
-    darkMode: boolean
-  }
-}
-export interface UserContext {
-  userId: string
-  plan: string
-  locale: string
+  show_documentation_feature: boolean;
+  color_scheme: 'light' | 'dark';
+  results_per_page: number;
+  advanced_settings: { logging: boolean };
 }
-// components/TypedComponent.tsx
-import { useFlag } from 'react-flagmint/client'
-import type { AppFlags } from '../types/flags'
-export default function TypedComponent() {
-  // TypeScript knows this returns boolean
-  const showBeta = useFlag<AppFlags['show-beta-feature']>('show-beta-feature', false)
-  // TypeScript knows this returns the union type
-  const plan = useFlag<AppFlags['user-plan']>('user-plan', 'free')
-  return (
-    <div>
-      {showBeta && <BetaFeature />}
-      <div>Plan: {plan}</div>
-    </div>
-  )
-}
+// In your component
+const colorScheme = useFlag<AppFlags['color_scheme']>('color_scheme', 'light');
+const resultsPerPage = useFlag<AppFlags['results_per_page']>('results_per_page', 10);
 ```
-### 4. Server-Side Rendering (SSR)
-#### Next.js App Router
+### Updating Context After Login
 ```tsx
-// app/providers.tsx
-'use client'
-import { FlagmintProvider } from 'react-flagmint/client'
-export default function Providers({ children, initialFlags = {} }) {
-  return (
-    <FlagmintProvider
-      options={{
-        apiKey: process.env.NEXT_PUBLIC_FLAGMINT_API_KEY!,
-        transportMode: 'websocket'
-      }}
-      initialFlags={initialFlags}
-    >
-      {children}
-    </FlagmintProvider>
-  )
-}
+function Dashboard() {
+  const { updateContext, isInitialized } = useFlagmint();
+  const user = useCurrentUser();
+  useEffect(() => {
+    if (user) {
+      updateContext({
+        userId: user.id,
+        plan: user.subscription.plan,
+        orgId: user.orgId,
+      });
+    }
+  }, [user?.id]);
-// app/page.tsx
-import { FlagClient } from 'flagmint-js-sdk'
-import Providers from './providers'
-import ClientComponent from './ClientComponent'
-export default async function Page() {
-  // Optionally preload flags on server
-  let initialFlags = {}
-  try {
-    const serverClient = new FlagClient({
-      apiKey: process.env.FLAGMINT_API_KEY!,
-      context: { server: true }
-    })
-    await serverClient.ready()
-    initialFlags = await serverClient.getFlags() // If this method exists
-  } catch (error) {
-    console.warn('Failed to load initial flags:', error)
-  }
-  return (
-    <Providers initialFlags={initialFlags}>
-      <ClientComponent />
-    </Providers>
-  )
+  if (!isInitialized) return <Spinner />;
+  return <DashboardContent />;
 }
 ```
-### 5. Context Updates
-Update user context dynamically:
+### Preventing Flash of Wrong Content
 ```tsx
-function UserSettings() {
-  const { updateContext } = useFlagmint()
-  const currentTheme = useFlag('user-theme', 'light')
-  const handleThemeChange = async (newTheme: string) => {
-    // Update context - flags will be re-evaluated
-    await updateContext({ theme: newTheme })
-  }
-  const handlePlanUpgrade = async (newPlan: string) => {
-    await updateContext({ plan: newPlan })
-    // Component will re-render with new plan-based flags
-  }
-  return (
-    <div>
-      <ThemeSelector onChange={handleThemeChange} />
-      <PlanUpgrade onUpgrade={handlePlanUpgrade} />
-    </div>
-  )
+function PricingPage() {
+  const isReady = useFlagmintReady();
+  const showNewPricing = useFlag<boolean>('new_pricing_page', false);
+  // Without isReady check, user briefly sees old pricing before flags load
+  if (!isReady) return <PricingSkeleton />;
+  return showNewPricing ? <NewPricing /> : <OldPricing />;
 }
 ```
-### 6. Loading States
+### Preview Mode (Local Evaluation)
-Handle loading states gracefully:
+Use preview mode in Storybook, tests, or demos to evaluate flags locally without a server connection:
 ```tsx
-function FeaturePage() {
-  const isReady = useFlagmintReady()
-  const showPremiumFeature = useFlag('premium-feature', false)
-  if (!isReady) {
-    return (
-      <div className="loading-container">
-        <Spinner />
-        <p>Loading personalized features...</p>
-      </div>
-    )
-  }
-  return (
-    <div>
-      <h1>Features</h1>
-      {showPremiumFeature ? (
-        <PremiumFeature />
-      ) : (
-        <UpgradeBanner />
-      )}
-    </div>
-  )
-}
+<FlagmintProvider
+  options={{
+    apiKey: 'preview',
+    previewMode: true,
+    rawFlags: {
+      new_dashboard: { value: true },
+      color_scheme: { value: 'dark' },
+      results_per_page: { value: 30 },
+    },
+  }}
+>
+  <App />
+</FlagmintProvider>
 ```
-### 7. Error Handling
+### Error Handling
 ```tsx
-<FlagmintProvider
+<FlagmintProvider
   options={{
-    apiKey: 'your-api-key',
+    apiKey: process.env.NEXT_PUBLIC_FLAGMINT_API_KEY!,
     onError: (error) => {
-      console.error('Flagmint error:', error)
-      // Send to error reporting service
-      errorReporting.captureException(error)
-    }
+      console.error('Flagmint error:', error);
+      errorReporting.captureException(error);
+    },
   }}
 >
   <App />
 </FlagmintProvider>
 ```
+---
 ## 🏗️ Framework Examples
-### Next.js (App Router)
+### Next.js App Router
 ```tsx
 // app/layout.tsx
-import Providers from './providers'
+import { FlagmintProviderSDK } from './FlagmintProviderSDK';
-export default function RootLayout({ children }) {
+export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
     <html lang="en">
       <body>
-        <Providers>{children}</Providers>
+        <FlagmintProviderSDK>
+          {children}
+        </FlagmintProviderSDK>
       </body>
     </html>
-  )
-}
-// app/providers.tsx
-'use client'
-import { FlagmintProvider } from 'react-flagmint/client'
-export default function Providers({ children }) {
-  return (
-    <FlagmintProvider
-      options={{
-        apiKey: process.env.NEXT_PUBLIC_FLAGMINT_API_KEY!,
-        transportMode: 'long-polling'
-      }}
-    >
-      {children}
-    </FlagmintProvider>
-  )
+  );
 }
 ```
@@ -474,30 +421,30 @@ export default function Providers({ children }) {
 ```tsx
 // src/main.tsx
-import React from 'react'
-import ReactDOM from 'react-dom/client'
-import { FlagmintProvider } from 'react-flagmint/client'
-import App from './App'
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { FlagmintProvider } from 'flagmint-react-sdk/client';
+import App from './App';
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <React.StrictMode>
-    <FlagmintProvider
+    <FlagmintProvider
       options={{
         apiKey: import.meta.env.VITE_FLAGMINT_API_KEY,
-        transportMode: 'websocket'
+        transportMode: 'websocket',
       }}
     >
       <App />
     </FlagmintProvider>
   </React.StrictMode>
-)
+);
 ```
 ### Remix
 ```tsx
 // app/root.tsx
-import { FlagmintProvider } from 'react-flagmint/client'
+import { FlagmintProvider } from 'flagmint-react-sdk/client';
 export default function App() {
   return (
@@ -507,10 +454,10 @@ export default function App() {
         <Links />
       </head>
       <body>
-        <FlagmintProvider
+        <FlagmintProvider
           options={{
             apiKey: process.env.FLAGMINT_API_KEY!,
-            transportMode: 'long-polling'
+            transportMode: 'long-polling', // Recommended for Remix
           }}
         >
           <Outlet />
@@ -518,73 +465,43 @@ export default function App() {
         <Scripts />
       </body>
     </html>
-  )
+  );
 }
 ```
+---
 ## ⚡ Performance
 ### Fine-grained Reactivity
-Only components that use specific flags will re-render when those flags change:
+Only the component reading a specific flag re-renders when that flag changes:
 ```tsx
-// ✅ Good: Only re-renders when 'feature-a' changes
+// ✅ Only re-renders when 'new_dashboard' changes
 function ComponentA() {
-  const featureA = useFlag('feature-a', false)
-  return <div>{featureA && <FeatureA />}</div>
+  const showDashboard = useFlag('new_dashboard', false);
+  return <div>{showDashboard && <NewDashboard />}</div>;
 }
-// ✅ Good: Only re-renders when 'feature-b' changes
+// ✅ Only re-renders when 'results_per_page' changes
 function ComponentB() {
-  const featureB = useFlag('feature-b', false)
-  return <div>{featureB && <FeatureB />}</div>
+  const limit = useFlag('results_per_page', 10);
+  return <ResultsList limit={limit} />;
 }
-// ❌ Avoid: Re-renders when ANY flag changes
+// ⚠️ Re-renders when ANY flag changes - use sparingly
 function ComponentAll() {
-  const allFlags = useFlags()
-  return <div>{allFlags['feature-a'] && <FeatureA />}</div>
+  const flags = useFlags();
+  return <div>{flags['new_dashboard'] && <NewDashboard />}</div>;
 }
 ```
-### Bundle Size
-- **react-flagmint**: ~3KB gzipped
-- **zustand**: ~2KB gzipped
-- **Total overhead**: ~5KB gzipped
-## 🔧 Development
-### Local Development
-```bash
-# Clone the monorepo
-git clone <repo-url>
-cd flagmint-monorepo
-# Install dependencies
-pnpm install
-# Build the library
-pnpm --filter react-flagmint build
-# Run the Next.js example
-pnpm dev:next
-```
-### Testing
+### Offline Cache
-```bash
-# Run tests
-pnpm test
-# Type checking
-pnpm typecheck
+Flags are cached in `localStorage` by default (`enableOfflineCache: true`). On the next page load, cached flags are served immediately while the fresh values load in the background - eliminating the loading state entirely for returning users.
-# Lint
-pnpm lint
-```
+---
 ## 📄 License
@@ -594,16 +511,15 @@ MIT
 1. Fork the repository
 2. Create a feature branch
-3. Make your changes
-4. Add tests
-5. Submit a pull request
+3. Make your changes with tests
+4. Submit a pull request
 ## 📞 Support
 - 📧 Email: support@flagmint.com
-- 🐛 Issues: [GitHub Issues](https://github.com/jtad009/flagmint-react-sdk/issues)
-- 📖 Docs: [Documentation](https://docs.flagmint.com)
+- 🐛 Issues: [GitHub Issues](https://github.com/flagmint/flagmint-react-sdk/issues)
+- 📖 Docs: [docs.flagmint.com](https://docs.flagmint.com)
 ---
-**Made with ❤️ by the Flagmint team**
+**Made with ❤️ by the Flagmint team**