@insforge/react

@insforge/react

Complete authentication solution for React applications. Production-ready components with full business logic included.

Why @insforge/react?

✅ 5-Minute Setup - One provider + one line of router config = done
✅ Built-in Auth UI - Use deployed auth pages (like Next.js middleware)
✅ Framework Agnostic - Works with any React framework
✅ Full TypeScript - Complete type safety out of the box
✅ Fully Customizable - Deep styling control when you need it

Quick Start

Get authentication working in your React app in 5 minutes.

1. Install

npm install @insforge/react
# or
yarn add @insforge/react
# or
pnpm add @insforge/react

2. Setup Provider

Wrap your app with InsforgeProvider:

// src/main.tsx (Vite) or src/index.tsx (CRA)
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { InsforgeProvider } from '@insforge/react';
import '@insforge/react/styles.css';
import App from './App';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <InsforgeProvider baseUrl={import.meta.env.VITE_INSFORGE_BASE_URL}>
      <App />
    </InsforgeProvider>
  </StrictMode>
);

3. Configure Router (Built-in Auth)

// src/App.tsx
import { createBrowserRouter, RouterProvider } from 'react-router-dom';
import { getInsforgeRoutes } from '@insforge/react/router';
import Home from './pages/Home';
import Dashboard from './pages/Dashboard';

const router = createBrowserRouter([
  { path: '/', element: <Home /> },
  
  ...getInsforgeRoutes({
    baseUrl: import.meta.env.VITE_INSFORGE_BASE_URL,
    builtInAuth: true
  }),
  
  { path: '/dashboard', element: <Dashboard /> }
]);

export default function App() {
  return <RouterProvider router={router} />;
}

What this does:

• Visiting /sign-in → Redirects to your-project.insforge.app/auth/sign-in
• Visiting /sign-up → Redirects to your-project.insforge.app/auth/sign-up
• After auth → Redirects back to /auth/callback → Goes to dashboard

4. Add Auth UI to Your Pages

// src/pages/Home.tsx
import { SignedIn, SignedOut, UserButton } from '@insforge/react';

export default function Home() {
  return (
    <div>
      <nav>
        <SignedOut>
          <a href="/sign-in">Sign In</a>
        </SignedOut>

        <SignedIn>
          <UserButton afterSignOutUrl="/" />
        </SignedIn>
      </nav>

      <h1>Welcome to My App!</h1>
    </div>
  );
}

That's it! 🎉 You now have production-ready authentication.

Router Configuration Options

Built-in Auth (Recommended)

Uses your deployed Insforge auth pages (includes all flows):

...getInsforgeRoutes({
  baseUrl: 'https://your-project.insforge.app',
  builtInAuth: true,  // Default
  paths: {
    signIn: '/sign-in',                // Sign in page
    signUp: '/sign-up',                // Sign up page
    verifyEmail: '/verify-email',      // Email verification page
    forgotPassword: '/forgot-password', // Request password reset
    resetPassword: '/reset-password',   // Reset password with token
    callback: '/auth/callback'          // OAuth callback handler
  }
})

Custom UI Components

Use package components with your own styling:

import { 
  SignIn, 
  SignUp, 
  ForgotPassword, 
  ResetPassword, 
  VerifyEmail 
} from '@insforge/react';

const router = createBrowserRouter([
  { path: '/', element: <Home /> },
  
  // Still need callback route for OAuth
  ...getInsforgeRoutes({
    baseUrl: import.meta.env.VITE_INSFORGE_BASE_URL,
    builtInAuth: false  // Don't redirect to deployed UI
  }),
  
  // Use package components for complete auth flows
  { path: '/sign-in', element: <SignIn afterSignInUrl="/dashboard" /> },
  { path: '/sign-up', element: <SignUp afterSignUpUrl="/dashboard" /> },
  { path: '/forgot-password', element: <ForgotPassword backToSignInUrl="/sign-in" /> },
  { path: '/reset-password', element: <ResetPassword token={searchParams.get('token')} /> },
  { path: '/verify-email', element: <VerifyEmail token={searchParams.get('token')} /> }
]);

Fully Custom UI

Build your own auth pages from scratch:

import { useAuth } from '@insforge/react';

function CustomSignIn() {
  const { signIn } = useAuth();
  
  const handleSubmit = async (e) => {
    e.preventDefault();
    await signIn(email, password);
    navigate('/dashboard');
  };
  
  return <form onSubmit={handleSubmit}>...</form>;
}

Core Features

Components

Pre-built with Business Logic:

• <SignIn /> - Complete sign-in with email/password & OAuth
• <SignUp /> - Registration with password validation & email verification
• <ForgotPassword /> - Request password reset with email validation
• <ResetPassword /> - Reset password with token validation
• <VerifyEmail /> - Verify email with automatic token handling
• <UserButton /> - User dropdown with sign-out
• <Protect /> - Route protection wrapper
• <SignedIn> / <SignedOut> - Conditional rendering
• <InsforgeCallback /> - OAuth callback handler

Form Components (Pure UI):

• <SignInForm /> - Sign-in UI without logic
• <SignUpForm /> - Sign-up UI without logic
• <ForgotPasswordForm /> - Password reset request UI
• <ResetPasswordForm /> - Password reset with token UI
• <VerifyEmailStatus /> - Email verification status UI

Atomic Components (14 total):

• <AuthContainer />, <AuthHeader />, <AuthFormField />, <AuthPasswordField />, <AuthEmailVerificationStep />, etc.

Hooks

const { signIn, signUp, signOut, isSignedIn, isLoaded } = useAuth();
const { user, updateUser, isLoaded } = useUser();
const { oauthProviders, authConfig, isLoaded } = usePublicAuthConfig();

Customization

Basic Styling

All components support appearance props:

<SignIn
  appearance={{
    container: "max-w-lg",
    card: "bg-white shadow-2xl",
    button: "bg-blue-600 hover:bg-blue-700"
  }}
/>

// Works with all auth components
<ForgotPassword
  appearance={{
    card: "bg-gradient-to-br from-indigo-50 to-white",
    button: "bg-indigo-600 hover:bg-indigo-700"
  }}
/>

Deep Customization (Hierarchical Appearance)

Style nested components through hierarchical structure:

<SignIn
  appearance={{
    card: "bg-gradient-to-br from-blue-50 to-white shadow-2xl",
    header: {
      title: "text-3xl font-bold text-purple-900",
      subtitle: "text-purple-600"
    },
    form: {
      emailField: {
        label: "text-gray-800 font-semibold",
        input: "border-purple-300 focus:border-purple-500 rounded-lg"
      },
      passwordField: {
        input: "border-purple-300 focus:border-purple-500 rounded-lg",
        forgotPasswordLink: "text-purple-600 hover:text-purple-800"
      }
    },
    button: "bg-purple-600 hover:bg-purple-700 rounded-lg h-12",
    link: {
      text: "text-gray-600",
      link: "text-purple-600 hover:text-purple-800 font-semibold"
    },
    oauth: {
      button: "border-2 hover:bg-gray-50 rounded-xl"
    }
  }}
/>

Complete Appearance Structure

All auth components (SignIn, SignUp, ForgotPassword, ResetPassword) support hierarchical appearance:

appearance?: {
  container?: string;              // Outermost wrapper
  card?: string;                   // Inner card box
  header?: {
    container?: string;            // Header wrapper
    title?: string;                // Title text
    subtitle?: string;             // Subtitle text
  };
  errorBanner?: string;            // Error message banner
  form?: {
    container?: string;            // Form wrapper
    emailField?: {                 // Available in SignIn, SignUp, ForgotPassword
      container?: string;
      label?: string;
      input?: string;
    };
    passwordField?: {              // Available in SignIn, SignUp, ResetPassword
      container?: string;
      label?: string;
      input?: string;
      forgotPasswordLink?: string; // SignIn only
      strengthIndicator?: {        // SignUp and ResetPassword
        container?: string;
        requirement?: string;
      };
    };
  };
  button?: string;                 // Submit button
  link?: {
    container?: string;            // Link section wrapper
    text?: string;                 // Link description text
    link?: string;                 // Actual link element
  };
  divider?: string;                // "or" divider (SignIn, SignUp)
  oauth?: {                        // OAuth section (SignIn, SignUp)
    container?: string;
    button?: string;
  };
}

Text Customization

All components support full text customization:

<SignIn
  title="Welcome Back!"
  subtitle="We're happy to see you again"
  emailLabel="Your Email Address"
  emailPlaceholder="[e-mail]"
  passwordLabel="Your Password"
  submitButtonText="Login Now"
  loadingButtonText="Signing you in..."
  signUpText="New to our platform?"
  signUpLinkText="Create an account"
  dividerText="or continue with"
/>

<ForgotPassword
  title="Reset Your Password"
  subtitle="Enter your email to receive a reset code"
  emailLabel="Email Address"
  submitButtonText="Send Reset Code"
  backToSignInText="Remember your password?"
  successTitle="Check Your Email"
  successMessage="We've sent a reset code to your inbox"
/>

Advanced Usage

Complete Component with Custom Logic

import { SignInForm, useAuth } from '@insforge/react';
import { useState } from 'react';

function CustomSignIn() {
  const { signIn } = useAuth();
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [error, setError] = useState('');
  const [loading, setLoading] = useState(false);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setLoading(true);
    setError('');
    
    try {
      await signIn(email, password);
      // Custom success logic
    } catch (err) {
      setError(err.message);
    } finally {
      setLoading(false);
    }
  };

  return (
    <SignInForm
      email={email}
      password={password}
      onEmailChange={setEmail}
      onPasswordChange={setPassword}
      onSubmit={handleSubmit}
      error={error}
      loading={loading}
      availableProviders={['google', 'github']}
      onOAuthClick={(provider) => {
        // Custom OAuth logic
      }}
    />
  );
}

Build from Atomic Components

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)}
          authConfig={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>
  );
}

Route Protection

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>
  );
}

TypeScript

Full TypeScript support with exported types:

import type {
  InsforgeUser,
  SignInProps,
  SignUpProps,
  ForgotPasswordProps,
  ResetPasswordProps,
  VerifyEmailProps,
  SignInAppearance,
  SignUpAppearance,
  ForgotPasswordAppearance,
  ResetPasswordAppearance,
  UserButtonProps,
  ProtectProps,
  ConditionalProps,
  InsforgeCallbackProps,
  SignInFormProps,
  SignUpFormProps,
  ForgotPasswordFormProps,
  ResetPasswordFormProps,
  VerifyEmailStatusProps,
  AuthFormFieldProps,
  OAuthProvider,
  EmailAuthConfig,
  InsforgeProviderProps,
  GetInsforgeRoutesConfig,
} from '@insforge/react';

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.

Validation Utilities

import { emailSchema, cn } from '@insforge/react/lib';

// Validate email with Zod
const result = emailSchema.safeParse('[e-mail]');

// Merge Tailwind classes
const className = cn('px-4 py-2', 'bg-blue-500', conditionalClass);

Available Atomic Components

Low-level building blocks for complete customization:

• <AuthBranding /> - Insforge branding footer
• <AuthContainer /> - Main container wrapper
• <AuthHeader /> - Title and subtitle display
• <AuthErrorBanner /> - Error message display
• <AuthFormField /> - Standard input field
• <AuthPasswordField /> - Password input with features
• <AuthPasswordStrengthIndicator /> - Password checklist
• <AuthSubmitButton /> - Submit button with states
• <AuthLink /> - Call-to-action link
• <AuthDivider /> - Visual separator
• <AuthOAuthButton /> - Single OAuth provider button
• <AuthOAuthProviders /> - Smart OAuth grid
• <AuthVerificationCodeInput /> - 6-digit OTP input
• <AuthEmailVerificationStep /> - Email verification step with countdown and resend

Support

• Documentation: https://docs.insforge.dev
• GitHub Issues: https://github.com/InsForge/InsForge/issues
• Discord Community: https://discord.com/invite/DvBtaEc9Jz

License

MIT © Insforge