@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

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

Environment Variables

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

Step 3: Configure Router (Built-in Auth)

The fastest way - Use deployed auth pages with Layout pattern:

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

const router = createBrowserRouter([
  {
    path: '/',
    element: <Layout />,
    children: [
      { index: true, element: <Home /> },

      { path: 'dashboard', element: <Dashboard /> }
    ]
  },

  // Add built-in auth redirect routes (sign-in, sign-up, forgot-password, etc.)
  ...getInsforgeRoutes({
    baseUrl: import.meta.env.VITE_INSFORGE_BASE_URL,
    afterSignInUrl="/dashboard"
    builtInAuth: true  // Redirects to deployed auth pages
  })
]);

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
• Visiting /forgot-password → Redirects to your-project.insforge.app/auth/forgot-password
• After auth → Backend redirects with token in URL → SDK auto-detects and stores token

4. Use Hooks & Components

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

export default function Home() {
  const { isSignedIn } = useAuth();
  const { user } = useUser();

  return (
    <div>
      <nav>
        <SignedOut>
          <a href="/sign-in">Sign In</a>
        </SignedOut>

        <SignedIn>
          <UserButton afterSignOutUrl="/" />
          <h1>Welcome, {user?.email}!</h1>
        </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
    forgotPassword: '/forgot-password', // Request password reset
  }
})

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 /> },

  // 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 /> },
]);

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

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="[email protected]"
  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) => {
        console.log(provider);
      }}
    />
  );
}

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

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

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

Support

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

License

MIT © Insforge