npm - @insforge/react - Versions diffs - 0.1.0 - Mend

@insforge/react 0.1.0

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

package/README.md ADDED Viewed

@@ -0,0 +1,849 @@
+# @insforge/react
+**Complete authentication solution for React applications.** Framework-agnostic components with full business logic included.
+## Why @insforge/react?
+✅ **Complete Package** - Not just UI, includes SDK integration, providers, and hooks
+✅ **Framework Agnostic** - Works with Next.js, Vite, Remix, or any React framework
+✅ **5-Minute Setup** - Provider + Components = done
+✅ **Full TypeScript** - Complete type safety out of the box
+✅ **Customizable** - Every component supports appearance props and text customization
+**Need just UI?** All components are exported separately for maximum flexibility.
+## Installation
+```bash
+npm install @insforge/react
+# or
+yarn add @insforge/react
+# or
+pnpm add @insforge/react
+```
+Dependencies automatically include `@insforge/sdk` for authentication logic.
+---
+## Quick Start
+### 1. Setup Provider
+Wrap your app with `InsforgeProvider` in the root:
+```tsx
+// React / Vite
+import { InsforgeProvider } from '@insforge/react';
+import '@insforge/react/styles.css';
+function App() {
+  return (
+    <InsforgeProvider baseUrl={import.meta.env.VITE_INSFORGE_BASE_URL}>
+      {/* Your app */}
+    </InsforgeProvider>
+  );
+}
+```
+```tsx
+// Next.js App Router
+'use client';
+import { InsforgeProvider } from '@insforge/react';
+import '@insforge/react/styles.css';
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <InsforgeProvider baseUrl={process.env.NEXT_PUBLIC_INSFORGE_BASE_URL}>
+          {children}
+        </InsforgeProvider>
+      </body>
+    </html>
+  );
+}
+```
+**Props:**
+- `baseUrl` (required): Your Insforge backend URL
+- `onAuthChange` (optional): Callback when auth state changes
+- `syncTokenToCookie` (optional): Custom function to sync token to cookies (for Next.js SSR)
+- `clearCookie` (optional): Custom function to clear cookie on sign out
+### 2. Use Pre-built Components
+The easiest way to add authentication:
+```tsx
+'use client'; // for Next.js
+import { SignIn, SignUp } from '@insforge/react';
+// Sign In Page
+export default function SignInPage() {
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-gray-50">
+      <SignIn
+        afterSignInUrl="/dashboard"
+        signUpUrl="/sign-up"
+      />
+    </div>
+  );
+}
+// Sign Up Page
+export default function SignUpPage() {
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-gray-50">
+      <SignUp
+        afterSignUpUrl="/dashboard"
+        signInUrl="/sign-in"
+      />
+    </div>
+  );
+}
+```
+### 3. Create Callback Page (for OAuth)
+Handle OAuth redirects:
+```tsx
+'use client'; // for Next.js
+import { InsforgeCallback } from '@insforge/react';
+export default function CallbackPage() {
+  return <InsforgeCallback />;
+}
+```
+### 4. Use Hooks & Components
+```tsx
+'use client'; // for Next.js
+import { SignedIn, SignedOut, UserButton, useAuth, useUser } from '@insforge/react';
+export default function Home() {
+  const { isSignedIn } = useAuth();
+  const { user } = useUser();
+  return (
+    <div>
+      <SignedOut>
+        <a href="/sign-in">Sign In</a>
+      </SignedOut>
+      <SignedIn>
+        <UserButton afterSignOutUrl="/" />
+        <h1>Welcome, {user?.email}!</h1>
+      </SignedIn>
+    </div>
+  );
+}
+```
+**That's it!** 🎉 Your React app now has production-ready authentication.
+---
+## How It Works
+```
+1. User visits Sign In page → Renders <SignIn> component
+   ↓
+2. User enters credentials → Component calls SDK methods
+   ↓
+3. SDK communicates with backend → Returns auth token
+   ↓
+4. Provider updates auth state → Components re-render
+   ↓
+5. User sees authenticated UI → Redirect to dashboard
+```
+**Architecture:**
+- **InsforgeProvider**: Manages authentication state globally
+- **SDK Integration**: All auth operations go through `@insforge/sdk`
+- **React Context**: Provides auth state to all child components
+- **Hooks**: Easy access to auth methods and user data
+---
+## Complete Components (with Business Logic)
+These components include full authentication logic:
+### `<SignIn />`
+Complete sign-in component with email/password and OAuth:
+```tsx
+import { SignIn } from '@insforge/react';
+import { useNavigate } from 'react-router-dom';
+function SignInPage() {
+  const navigate = useNavigate();
+  return (
+    <SignIn
+      afterSignInUrl="/dashboard"
+      signUpUrl="/sign-up"
+      forgotPasswordUrl="/forgot-password"
+      onSuccess={(user, accessToken) => {
+        console.log('Signed in:', user);
+      }}
+      onError={(error) => {
+        console.error('Error:', error);
+      }}
+      onRedirect={(url) => navigate(url)}
+      // Customization
+      title="Welcome Back"
+      subtitle="Sign in to continue"
+      appearance={{
+        containerClassName: "shadow-xl",
+        buttonClassName: "bg-blue-600"
+      }}
+    />
+  );
+}
+```
+**Key Features:**
+- Email/password authentication
+- OAuth provider buttons (auto-detected from backend)
+- Password visibility toggle
+- Error handling
+- Loading states
+- Customizable text and styling
+### `<SignUp />`
+Complete sign-up component with password strength validation:
+```tsx
+import { SignUp } from '@insforge/react';
+function SignUpPage() {
+  return (
+    <SignUp
+      afterSignUpUrl="/onboarding"
+      signInUrl="/sign-in"
+      onSuccess={(user, accessToken) => {
+        // Track sign-up event
+        analytics.track('user_signed_up', { userId: user.id });
+      }}
+    />
+  );
+}
+```
+**Key Features:**
+- Email/password registration
+- Real-time password strength indicator
+- OAuth provider buttons
+- Form validation
+- Customizable requirements
+### `<UserButton />`
+User profile dropdown with sign-out:
+```tsx
+import { UserButton } from '@insforge/react';
+function Header() {
+  return (
+    <header>
+      <nav>
+        {/* Your navigation */}
+      </nav>
+      <UserButton
+        afterSignOutUrl="/"
+        mode="detailed" // or "simple"
+        appearance={{
+          buttonClassName: "hover:bg-gray-100",
+          nameClassName: "text-gray-900",
+          emailClassName: "text-gray-600"
+        }}
+      />
+    </header>
+  );
+}
+```
+**Modes:**
+- `detailed`: Shows avatar + name + email
+- `simple`: Shows avatar only
+### `<Protect />`
+Protected content with conditional rendering:
+```tsx
+import { Protect } from '@insforge/react';
+function Dashboard() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      {/* Simple protection */}
+      <Protect redirectTo="/sign-in">
+        <UserContent />
+      </Protect>
+      {/* Role-based protection */}
+      <Protect
+        redirectTo="/unauthorized"
+        condition={(user) => user.role === 'admin'}
+      >
+        <AdminPanel />
+      </Protect>
+    </div>
+  );
+}
+```
+### `<SignedIn>` / `<SignedOut>`
+Conditional rendering based on auth state:
+```tsx
+import { SignedIn, SignedOut } from '@insforge/react';
+function NavBar() {
+  return (
+    <nav>
+      <SignedOut>
+        <a href="/sign-in">Sign In</a>
+        <a href="/sign-up">Sign Up</a>
+      </SignedOut>
+      <SignedIn>
+        <a href="/dashboard">Dashboard</a>
+        <UserButton />
+      </SignedIn>
+    </nav>
+  );
+}
+```
+### `<InsforgeCallback />`
+OAuth callback handler (3 lines instead of 70+):
+```tsx
+'use client';
+import { InsforgeCallback } from '@insforge/react';
+export default function CallbackPage() {
+  return <InsforgeCallback redirectTo="/dashboard" />;
+}
+```
+---
+## Hooks
+### `useAuth()`
+Access authentication methods:
+```tsx
+import { useAuth } from '@insforge/react';
+function LoginButton() {
+  const { signIn, signUp, signOut, isSignedIn, isLoaded } = useAuth();
+  const handleSignIn = async () => {
+    try {
+      await signIn('user@example.com', 'password');
+      // Redirect or update UI
+    } catch (error) {
+      console.error('Sign in failed:', error);
+    }
+  };
+  if (!isLoaded) return <div>Loading...</div>;
+  return (
+    <button onClick={isSignedIn ? signOut : handleSignIn}>
+      {isSignedIn ? 'Sign Out' : 'Sign In'}
+    </button>
+  );
+}
+```
+**Returns:**
+- `signIn(email, password)` - Sign in with email/password
+- `signUp(email, password)` - Sign up new user
+- `signOut()` - Sign out current user
+- `isSignedIn` - Boolean auth state
+- `isLoaded` - Boolean loading state
+### `useUser()`
+Access user data:
+```tsx
+import { useUser } from '@insforge/react';
+function UserProfile() {
+  const { user, isLoaded, updateUser } = useUser();
+  if (!isLoaded) return <div>Loading...</div>;
+  if (!user) return <div>Not signed in</div>;
+  const handleUpdate = async () => {
+    await updateUser({ name: 'New Name' });
+  };
+  return (
+    <div>
+      <p>Email: {user.email}</p>
+      <p>Name: {user.name}</p>
+      <img src={user.avatarUrl} alt="Avatar" />
+      <button onClick={handleUpdate}>Update Name</button>
+    </div>
+  );
+}
+```
+**Returns:**
+- `user` - User object with id, email, name, avatarUrl
+- `isLoaded` - Boolean loading state
+- `updateUser(data)` - Update user profile
+- `setUser(user)` - Manually set user state
+### `usePublicAuthConfig()`
+Get OAuth providers and password requirements:
+```tsx
+import { usePublicAuthConfig } from '@insforge/react';
+function SignInPage() {
+  const { oauthProviders, emailConfig, isLoaded } = usePublicAuthConfig();
+  if (!isLoaded) return <div>Loading...</div>;
+  return (
+    <div>
+      <p>Available OAuth: {oauthProviders.join(', ')}</p>
+      <p>Password min length: {emailConfig?.passwordMinLength}</p>
+    </div>
+  );
+}
+```
+**⚠️ Important:** Only use this hook in SignIn/SignUp components to avoid unnecessary API calls.
+---
+## UI Form Components (Pure UI)
+Build custom auth flows with pre-built forms:
+### `<SignInForm />`
+```tsx
+import { SignInForm } from '@insforge/react';
+import { useState } from 'react';
+function CustomSignIn() {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [error, setError] = useState('');
+  const [loading, setLoading] = useState(false);
+  const handleSubmit = async (e) => {
+    e.preventDefault();
+    setLoading(true);
+    // Your auth logic
+  };
+  return (
+    <SignInForm
+      email={email}
+      password={password}
+      onEmailChange={setEmail}
+      onPasswordChange={setPassword}
+      onSubmit={handleSubmit}
+      error={error}
+      loading={loading}
+      availableProviders={['google', 'github']}
+      onOAuthClick={(provider) => handleOAuth(provider)}
+    />
+  );
+}
+```
+**Other Form Components:**
+- `<SignUpForm />` - Sign up with password strength
+- `<ForgotPasswordForm />` - Request password reset
+- `<ResetPasswordForm />` - Reset password with token
+- `<VerifyEmailStatus />` - Email verification status
+---
+## Atomic Components (Maximum Flexibility)
+Build completely custom UIs:
+```tsx
+import {
+  AuthContainer,
+  AuthHeader,
+  AuthFormField,
+  AuthPasswordField,
+  AuthSubmitButton,
+  AuthErrorBanner,
+  AuthDivider,
+  AuthOAuthProviders,
+  AuthLink,
+} from '@insforge/react';
+function CompletelyCustomAuth() {
+  return (
+    <AuthContainer
+      appearance={{
+        containerClassName: "max-w-md",
+        cardClassName: "bg-white shadow-2xl"
+      }}
+    >
+      <AuthHeader
+        title="Welcome to MyApp"
+        subtitle="Sign in to continue"
+        appearance={{
+          titleClassName: "text-3xl text-blue-900"
+        }}
+      />
+      <AuthErrorBanner error={error} />
+      <form onSubmit={handleSubmit}>
+        <AuthFormField
+          id="email"
+          type="email"
+          label="Email"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          appearance={{
+            inputClassName: "border-blue-500"
+          }}
+        />
+        <AuthPasswordField
+          id="password"
+          label="Password"
+          value={password}
+          onChange={(e) => setPassword(e.target.value)}
+          emailAuthConfig={config}
+          showStrengthIndicator
+        />
+        <AuthSubmitButton isLoading={loading}>
+          Sign In
+        </AuthSubmitButton>
+      </form>
+      <AuthDivider text="or" />
+      <AuthOAuthProviders
+        providers={['google', 'github', 'discord']}
+        onClick={handleOAuth}
+        loading={oauthLoading}
+      />
+      <AuthLink
+        text="Don't have an account?"
+        linkText="Sign up"
+        href="/sign-up"
+      />
+    </AuthContainer>
+  );
+}
+```
+**Available Atomic Components:**
+- `AuthContainer` - Main wrapper with branding
+- `AuthHeader` - Title and subtitle
+- `AuthErrorBanner` - Error messages
+- `AuthFormField` - Standard input
+- `AuthPasswordField` - Password with toggle
+- `AuthPasswordStrengthIndicator` - Password checklist
+- `AuthSubmitButton` - Loading button
+- `AuthLink` - Navigation link
+- `AuthDivider` - Visual separator
+- `AuthOAuthButton` - Single OAuth button
+- `AuthOAuthProviders` - OAuth grid
+- `AuthVerificationCodeInput` - 6-digit OTP
+- `AuthBranding` - Insforge branding
+---
+## Customization
+### Appearance Props
+All components support Tailwind className overrides:
+```tsx
+<SignIn
+  appearance={{
+    containerClassName: "shadow-2xl max-w-lg",
+    cardClassName: "bg-gradient-to-br from-blue-50 to-white",
+    formClassName: "space-y-6",
+    buttonClassName: "bg-blue-600 hover:bg-blue-700 h-12"
+  }}
+/>
+<UserButton
+  appearance={{
+    buttonClassName: "hover:bg-gray-100 rounded-full",
+    nameClassName: "text-gray-900 font-semibold",
+    emailClassName: "text-gray-500",
+    dropdownClassName: "shadow-xl"
+  }}
+/>
+```
+### Text Customization
+All text is customizable:
+```tsx
+<SignIn
+  title="Welcome Back!"
+  subtitle="We're happy to see you again"
+  emailLabel="Your Email Address"
+  emailPlaceholder="you@company.com"
+  passwordLabel="Your Password"
+  submitButtonText="Login Now"
+  loadingButtonText="Signing you in..."
+  signUpText="New to our platform?"
+  signUpLinkText="Create an account"
+  dividerText="or continue with"
+/>
+```
+---
+## Framework Integration
+### Next.js (App Router)
+```tsx
+// app/layout.tsx
+'use client';
+import { InsforgeProvider } from '@insforge/react';
+import '@insforge/react/styles.css';
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <InsforgeProvider
+          baseUrl={process.env.NEXT_PUBLIC_INSFORGE_BASE_URL}
+          syncTokenToCookie={async (token) => {
+            await fetch('/api/auth', {
+              method: 'POST',
+              body: JSON.stringify({ token })
+            });
+            return true;
+          }}
+          clearCookie={async () => {
+            await fetch('/api/auth', { method: 'DELETE' });
+          }}
+        >
+          {children}
+        </InsforgeProvider>
+      </body>
+    </html>
+  );
+}
+```
+### Vite / React
+```tsx
+// src/main.tsx
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { BrowserRouter } from 'react-router-dom';
+import { InsforgeProvider } from '@insforge/react';
+import '@insforge/react/styles.css';
+import App from './App';
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <BrowserRouter>
+      <InsforgeProvider baseUrl={import.meta.env.VITE_INSFORGE_BASE_URL}>
+        <App />
+      </InsforgeProvider>
+    </BrowserRouter>
+  </StrictMode>
+);
+```
+### Remix
+```tsx
+// app/root.tsx
+import { InsforgeProvider } from '@insforge/react';
+import '@insforge/react/styles.css';
+export default function App() {
+  return (
+    <html>
+      <body>
+        <InsforgeProvider baseUrl={process.env.INSFORGE_BASE_URL}>
+          <Outlet />
+        </InsforgeProvider>
+      </body>
+    </html>
+  );
+}
+```
+---
+## TypeScript
+Full TypeScript support with exported types:
+```tsx
+import type {
+  InsforgeUser,
+  SignInProps,
+  SignUpProps,
+  UserButtonProps,
+  ProtectProps,
+  ConditionalProps,
+  InsforgeCallbackProps,
+  SignInFormProps,
+  SignUpFormProps,
+  AuthFormFieldProps,
+  OAuthProvider,
+  EmailAuthConfig,
+  InsforgeProviderProps,
+} from '@insforge/react';
+```
+---
+## API Reference
+### InsforgeProvider Props
+```tsx
+interface InsforgeProviderProps {
+  baseUrl: string;                                      // Insforge backend URL
+  onAuthChange?: (user: InsforgeUser | null) => void;   // Auth state callback
+  syncTokenToCookie?: (token: string) => Promise<boolean>; // Custom cookie sync
+  clearCookie?: () => Promise<void>;                    // Custom cookie clear
+}
+```
+### SignIn / SignUp Props
+```tsx
+interface SignInProps {
+  afterSignInUrl?: string;          // Redirect after sign in
+  signUpUrl?: string;               // Link to sign up page
+  forgotPasswordUrl?: string;       // Link to forgot password
+  onSuccess?: (user, token) => void; // Success callback
+  onError?: (error: Error) => void;  // Error callback
+  onRedirect?: (url: string) => void; // Custom redirect handler
+  title?: string;                    // Custom title
+  subtitle?: string;                 // Custom subtitle
+  appearance?: {                     // Custom styling
+    containerClassName?: string;
+    cardClassName?: string;
+    formClassName?: string;
+    buttonClassName?: string;
+  };
+  // ... more text customization props
+}
+```
+### InsforgeCallback Props
+```tsx
+interface InsforgeCallbackProps {
+  redirectTo?: string;              // Custom redirect destination
+  onSuccess?: () => void;           // Success callback
+  onError?: (error: string) => void; // Error callback
+  loadingComponent?: ReactNode;     // Custom loading UI
+  onRedirect?: (url: string) => void; // Custom redirect handler
+}
+```
+---
+## Validation Utilities
+```tsx
+import { emailSchema, cn } from '@insforge/react';
+// Validate email with Zod
+const result = emailSchema.safeParse('user@example.com');
+// Merge Tailwind classes
+const className = cn('px-4 py-2', 'bg-blue-500', conditionalClass);
+```
+---
+## OAuth Providers
+Built-in support for 10+ OAuth providers:
+- Google
+- GitHub
+- Discord
+- Apple
+- Microsoft
+- Facebook
+- LinkedIn
+- Instagram
+- TikTok
+- Spotify
+- X (Twitter)
+Providers are auto-detected from your backend configuration.
+---
+## Why @insforge/react?
+**vs. Building Custom Auth:**
+- ⚡️ 5 minutes vs 2+ days of development
+- 🔒 Production-ready security built-in
+- 🎨 Customizable when needed, works out of the box
+- 🚀 No framework lock-in
+**vs. Other Auth Libraries:**
+- 📦 Complete package (not just UI)
+- 🎯 Framework agnostic (works everywhere)
+- 🤖 SDK-first approach (consistent API)
+- 💰 Self-hosted (no vendor lock-in)
+---
+## Examples
+Check out example integrations:
+- [Next.js App Router](./examples/nextjs)
+- [Vite + React Router](./examples/vite)
+- [Remix](./examples/remix)
+---
+## Support
+- **Documentation**: https://docs.insforge.dev
+- **GitHub Issues**: https://github.com/InsForge/InsForge/issues
+- **Discord Community**: https://discord.com/invite/DvBtaEc9Jz
+## License
+MIT © Insforge