npm - flagmint-react-sdk - Versions diffs - 0.7.10 → 0.7.12 - Mend

flagmint-react-sdk 0.7.10 → 0.7.12

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 (2) hide show

package/README.md +609 -0
package/package.json +2 -2

package/README.md ADDED Viewed

@@ -0,0 +1,609 @@
+# flagmint-react-sdk
+A React wrapper for [flagmint-js-sdk](https://www.npmjs.com/package/flagmint-js-sdk) that provides React-specific hooks and context with fine-grained reactivity powered by Zustand.
+## ✨ Features
+- 🎯 **Fine-grained reactivity** - Only components using specific flags re-render when those flags change
+- 🚀 **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
+## 📦 Installation
+```bash
+npm install react-flagmint flagmint-js-sdk
+# or
+pnpm add react-flagmint flagmint-js-sdk
+# or
+yarn add react-flagmint flagmint-js-sdk
+```
+## 🚀 Quick Start
+### 1. Basic Setup
+```tsx
+// app/providers.tsx (Next.js App Router)
+'use client'
+import { FlagmintProvider } from 'react-flagmint/client'
+export default function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <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'
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <html>
+      <body>
+        <Providers>
+          {children}
+        </Providers>
+      </body>
+    </html>
+  )
+}
+```
+### 2. Using Flags in Components
+```tsx
+// components/FeatureComponent.tsx
+'use client'
+import { useFlag, useFlags, useFlagmintReady } from 'react-flagmint/client'
+export default function FeatureComponent() {
+  const showNewFeature = useFlag('new-dashboard', false)
+  const userPlan = useFlag('user-plan', 'free')
+  const isReady = useFlagmintReady()
+  if (!isReady) {
+    return <div>Loading flags...</div>
+  }
+  return (
+    <div>
+      {showNewFeature && <NewDashboard />}
+      <div>Current plan: {userPlan}</div>
+    </div>
+  )
+}
+```
+## 📚 API Reference
+### FlagmintProvider
+The provider component that initializes the FlagClient and provides flag context to your app.
+```tsx
+<FlagmintProvider
+  options={FlagClientOptions}
+  initialFlags={{}}
+  deferInitialization={false}
+>
+  {children}
+</FlagmintProvider>
+```
+#### Props
+| 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 |
+#### FlagClientOptions
+```tsx
+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
+}
+```
+### Hooks
+#### useFlag(key, fallback?)
+Get a specific flag value with fine-grained reactivity.
+```tsx
+const showFeature = useFlag('feature-name', false)
+const userTier = useFlag('user-tier', 'free')
+const config = useFlag('app-config', { theme: 'light' })
+```
+**Parameters:**
+- `key: string` - The flag key
+- `fallback?: T` - Default value if flag is not found
+**Returns:** The flag value or fallback
+#### useFlags()
+Get all currently loaded flags.
+```tsx
+const allFlags = useFlags()
+console.log(allFlags) // { 'feature-a': true, 'user-tier': 'pro' }
+```
+**Returns:** Object containing all loaded flags
+#### useFlagmint()
+Get access to the FlagClient instance and utilities.
+```tsx
+const { client, isReady, isInitialized, updateContext } = useFlagmint()
+// Update user context
+await updateContext({ userId: 'new-user', plan: 'enterprise' })
+```
+**Returns:**
+```tsx
+{
+  client: FlagClient | null
+  isReady: boolean
+  isInitialized: boolean
+  updateContext: (context: Record<string, any>) => Promise<void>
+}
+```
+#### useFlagmintReady()
+Check if the FlagClient is ready to serve flags.
+```tsx
+const isReady = useFlagmintReady()
+if (!isReady) {
+  return <LoadingSpinner />
+}
+```
+#### useFlagClient()
+Get direct access to the FlagClient instance.
+```tsx
+const client = useFlagClient<MyFlagTypes>()
+const specificFlag = client?.getFlag('feature-x', false)
+```
+## 🔧 Usage Patterns
+### 1. Auto-initialization (Default)
+Best when user context is available immediately:
+```tsx
+function App() {
+  return (
+    <FlagmintProvider
+      options={{
+        apiKey: 'your-api-key',
+        context: {
+          userId: getCurrentUser().id,
+          plan: getCurrentUser().plan
+        }
+      }}
+    >
+      <Dashboard />
+    </FlagmintProvider>
+  )
+}
+```
+### 2. Deferred Initialization
+Perfect for authentication flows:
+```tsx
+// Provider with deferred initialization
+<FlagmintProvider
+  options={{
+    apiKey: 'your-api-key',
+    context: {} // Empty initially
+  }}
+  deferInitialization={true}
+>
+  <App />
+</FlagmintProvider>
+// 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
+Define your flag types for better type safety:
+```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
+}
+// 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>
+  )
+}
+```
+### 4. Server-Side Rendering (SSR)
+#### Next.js App Router
+```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>
+  )
+}
+// 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>
+  )
+}
+```
+### 5. Context Updates
+Update user context dynamically:
+```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>
+  )
+}
+```
+### 6. Loading States
+Handle loading states gracefully:
+```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>
+  )
+}
+```
+### 7. Error Handling
+```tsx
+<FlagmintProvider
+  options={{
+    apiKey: 'your-api-key',
+    onError: (error) => {
+      console.error('Flagmint error:', error)
+      // Send to error reporting service
+      errorReporting.captureException(error)
+    }
+  }}
+>
+  <App />
+</FlagmintProvider>
+```
+## 🏗️ Framework Examples
+### Next.js (App Router)
+```tsx
+// app/layout.tsx
+import Providers from './providers'
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        <Providers>{children}</Providers>
+      </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>
+  )
+}
+```
+### Vite + React
+```tsx
+// src/main.tsx
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import { FlagmintProvider } from 'react-flagmint/client'
+import App from './App'
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <FlagmintProvider
+      options={{
+        apiKey: import.meta.env.VITE_FLAGMINT_API_KEY,
+        transportMode: 'websocket'
+      }}
+    >
+      <App />
+    </FlagmintProvider>
+  </React.StrictMode>
+)
+```
+### Remix
+```tsx
+// app/root.tsx
+import { FlagmintProvider } from 'react-flagmint/client'
+export default function App() {
+  return (
+    <html>
+      <head>
+        <Meta />
+        <Links />
+      </head>
+      <body>
+        <FlagmintProvider
+          options={{
+            apiKey: process.env.FLAGMINT_API_KEY!,
+            transportMode: 'long-polling'
+          }}
+        >
+          <Outlet />
+        </FlagmintProvider>
+        <Scripts />
+      </body>
+    </html>
+  )
+}
+```
+## ⚡ Performance
+### Fine-grained Reactivity
+Only components that use specific flags will re-render when those flags change:
+```tsx
+// ✅ Good: Only re-renders when 'feature-a' changes
+function ComponentA() {
+  const featureA = useFlag('feature-a', false)
+  return <div>{featureA && <FeatureA />}</div>
+}
+// ✅ Good: Only re-renders when 'feature-b' changes
+function ComponentB() {
+  const featureB = useFlag('feature-b', false)
+  return <div>{featureB && <FeatureB />}</div>
+}
+// ❌ Avoid: Re-renders when ANY flag changes
+function ComponentAll() {
+  const allFlags = useFlags()
+  return <div>{allFlags['feature-a'] && <FeatureA />}</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
+```bash
+# Run tests
+pnpm test
+# Type checking
+pnpm typecheck
+# Lint
+pnpm lint
+```
+## 📄 License
+MIT
+## 🤝 Contributing
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. 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)
+---
+**Made with ❤️ by the Flagmint team**

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "flagmint-react-sdk",
-  "version": "0.7.10",
+  "version": "0.7.12",
   "description": "React wrapper for flagmint-js-sdk",
   "type": "module",
   "sideEffects": false,
@@ -31,7 +31,7 @@
     "react-dom": ">=18.0.0"
   },
   "dependencies": {
-    "flagmint-js-sdk": "^1.2.3",
+    "flagmint-js-sdk": "^1.2.5",
     "zustand": "^4.4.0"
   },
   "devDependencies": {