@insforge/react

@insforge/react

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

Why @insforge/react?

✅ Framework Agnostic - Works with any React setup (Vite, CRA, or no bundler)
✅ Zero Router Dependencies - Use with any routing solution or none at all
✅ Production Ready - Complete auth flows with business logic included
✅ Full TypeScript - Complete type safety out of the box

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

Required Peer Dependencies:

npm install react@^19.0.0 react-dom@^19.0.0

Environment Variables

# .env
VITE_INSFORGE_BASE_URL=https://your-project.insforge.app/

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 App from './App';

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

3. Use Components & Hooks

Now you can use authentication components and hooks anywhere in your app:

// src/App.tsx
import { SignIn, SignedIn, SignedOut, UserButton, useAuth } from '@insforge/react';

export default function App() {
  const { isSignedIn, isLoaded } = useAuth();

  if (!isLoaded) {
    return <div>Loading...</div>;
  }

  return (
    <div>
      <SignedOut>
        <SignIn />
      </SignedOut>

      <SignedIn>
        <nav>
          <UserButton afterSignOutUrl="/" />
        </nav>
        <h1>Welcome to your dashboard!</h1>
      </SignedIn>
    </div>
  );
}

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

Usage Patterns

Option 1: Pre-built Components (Fastest)

Use complete auth flows with built-in UI and logic:

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

// In your app
<SignIn />  // Complete sign-in flow
<SignUp />  // Complete sign-up flow with email verification
<ForgotPassword />  // Password reset request + verification
<ResetPassword />  // Reset password with token (from URL params)

Option 2: Form Components (UI Only)

Use UI components and add your own 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) => {
    e.preventDefault();
    setLoading(true);
    const result = await signIn(email, password);
    if ('error' in result) {
      setError(result.error);
    }
    setLoading(false);
  };

  return (
    <SignInForm
      email={email}
      password={password}
      onEmailChange={setEmail}
      onPasswordChange={setPassword}
      onSubmit={handleSubmit}
      error={error}
      loading={loading}
    />
  );
}

Option 3: Hooks Only (Headless)

Build completely custom UI using authentication hooks:

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

function CustomAuthForm() {
  const { signIn, signUp, isLoaded } = useAuth();

  const handleLogin = async (email: string, password: string) => {
    const result = await signIn(email, password);
    if ('error' in result) {
      console.error(result.error);
    } else {
      console.log('Signed in!');
    }
  };

  return <form>...your custom UI...</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

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

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

Conditional Rendering

Control what users see based on auth state:

import { SignedIn, SignedOut, Protect } from '@insforge/react';

function App() {
  return (
    <>
      <SignedOut>
        <SignIn />
      </SignedOut>

      <SignedIn>
        <Dashboard />
      </SignedIn>

      {/* Or use Protect for specific sections */}
      <Protect redirectTo="/sign-in">
        <ProtectedContent />
      </Protect>
    </>
  );
}

Build from Atomic Components

import {
  AuthContainer,
  AuthHeader,
  AuthFormField,
  AuthPasswordField,
  AuthSubmitButton,
  AuthErrorBanner,
  AuthDivider,
  AuthOAuthProviders,
  AuthLink,
} from '@insforge/react';

function CompletelyCustomAuth() {
  return (
    <AuthContainer>
      <AuthHeader title="Welcome to MyApp" subtitle="Sign in to continue" />

      <AuthErrorBanner error={error} />

      <form onSubmit={handleSubmit}>
        <AuthFormField
          id="email"
          type="email"
          label="Email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
        />

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

Content Protection

Protect specific content or sections:

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

function Dashboard() {
  return (
    <div>
      <h1>Dashboard</h1>

      {/* Simple protection - shows nothing if not signed in */}
      <Protect>
        <UserContent />
      </Protect>

      {/* Custom condition - e.g., role-based */}
      <Protect condition={(user) => user.email.endsWith('@admin.com')}>
        <AdminPanel />
      </Protect>
    </div>
  );
}

Note: <Protect> is for conditional rendering only. For route-level protection, use your router's authentication guards with useAuth() hook.

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.

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

Framework Integration

Next.js

For Next.js App Router with full SSR support:

npm install @insforge/nextjs

See @insforge/nextjs documentation

Support

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

License

MIT © Insforge