# @insforge/react
**Framework-agnostic authentication solution for React applications.** Production-ready components with full business logic included.
> **✨ CSS-in-JS**: All components now use Emotion CSS-in-JS for zero FOUC in SSR environments. No CSS imports needed!
## Why @insforge/react?
✅ **Framework Agnostic** - Works with any React setup (Vite, CRA, or no bundler)
✅ **Zero Router Dependencies** - Built-in navigation abstraction works with any routing solution
✅ **Route Protection** - Built-in `RouteGuard` for vanilla React apps
✅ **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
```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 & Route Guard
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(
);
```
### 3. Use Components & Hooks
Now you can use authentication components and hooks anywhere in your app:
```tsx
// src/App.tsx
import { SignInButton, SignUpButton, SignedIn, SignedOut, UserButton } from '@insforge/react';
export default function App() {
return (
Welcome to your dashboard!
);
}
```
**That's it!** 🎉 Your app is now protected with authentication.
---
## Usage Patterns
### Option 1: Pre-built Components (Fastest)
Use complete auth flows with built-in UI and logic:
```tsx
import { SignIn, SignUp, ForgotPassword, ResetPassword } from '@insforge/react';
// In your app
// Complete sign-in flow
// Complete sign-up flow with email verification
// Password reset request + verification
// Reset password with token (from URL params)
```
### Option 2: Form Components (UI Only)
Use UI components and add your own 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) => {
e.preventDefault();
setLoading(true);
const result = await signIn(email, password);
if ('error' in result) {
setError(result.error);
}
setLoading(false);
};
return (
);
}
```
### Option 3: Hooks Only (Headless)
Build completely custom UI using authentication hooks:
```tsx
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 ;
}
```
---
## Core Features
### Components
**Pre-built with Business Logic:**
- `` - Complete sign-in with email/password & OAuth
- `` - Registration with password validation & email verification
- `` - Request password reset with email validation
- `` - Reset password with token validation
- `` - Verify email with automatic token handling
- `` - User dropdown with sign-out
- `` - **NEW:** App-level route protection for vanilla React
- `` - Component-level protection wrapper
- `` / `` - Conditional rendering
**Form Components (Pure UI):**
- `` - Sign-in UI without logic
- `` - Sign-up UI without logic
- `` - Password reset request UI
- `` - Password reset with token UI
- `` - Email verification status UI
**Atomic Components (14 total):**
- ``, ``, ``, ``, ``, etc.
### Hooks
```tsx
// Authentication state and methods
const {
signIn,
signUp,
signOut,
isSignedIn,
isLoaded,
baseUrl, // From provider
afterSignInUrl, // From provider
} = useAuth();
// Or use useInsforge (same as useAuth)
const context = useInsforge();
// User information
const { user, updateUser, isLoaded } = useUser();
// Public auth configuration (OAuth providers, password requirements, etc.)
const { oauthProviders, authConfig, isLoaded } = usePublicAuthConfig();
```
---
## Customization
### Text Customization
All components support full text customization:
```tsx
```
---
## Advanced Usage
### Conditional Rendering
Control what users see based on auth state:
```tsx
import { SignedIn, SignedOut, Protect } from '@insforge/react';
function App() {
return (
<>
{/* Or use Protect for specific sections */}
);
}
```
### Build from Atomic Components
```tsx
import {
AuthContainer,
AuthHeader,
AuthFormField,
AuthPasswordField,
AuthSubmitButton,
AuthErrorBanner,
AuthDivider,
AuthOAuthProviders,
AuthLink,
} from '@insforge/react';
function CompletelyCustomAuth() {
return (
);
}
```
### Content Protection
Protect specific content or sections:
```tsx
import { Protect } from '@insforge/react';
function Dashboard() {
return (
Dashboard
{/* Simple protection - shows nothing if not signed in */}
{/* With redirect */}
{/* Custom condition - e.g., role-based */}
user.email.endsWith('@admin.com')} redirectTo="/unauthorized">