npm package: @insforge/react-router
Description: React Router adapter for Insforge authentication - extends @insforge/react with React Router navigation
Author: Insforge
Latest version: 1.1.7
Deprecated: This package is deprecated. Use @insforge/sdk directly instead.

# @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

```bash
npm install @insforge/react
# or
yarn add @insforge/react
# or
pnpm add @insforge/react
```

#### Environment Variables

```bash .env
VITE_INSFORGE_BASE_URL=https://your-project.insforge.app/
```

### 2. Setup Provider

Wrap your app with `InsforgeProvider`:

```tsx
// 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:

```tsx src/App.tsx
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

```tsx
// 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):

```tsx
...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:

```tsx
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:

```tsx
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

```tsx
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:

```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"
/>

<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

```tsx
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

```tsx
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

```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>
  );
}
```

---

## 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