@vergeinfosoft/react

React SDK for Verge Auth - Single-line authentication integration for your React applications.

Installation

npm install @vergeinfosoft/react

Quick Start

One-Line Integration

Wrap your entire app with the VergeAuth component:

import { VergeAuth } from '@vergeinfosoft/react';

function App() {
  return (
    <VergeAuth>
      <YourApp />
    </VergeAuth>
  );
}

That's it! Your app is now protected with Verge Auth.

With Custom Configuration

import { VergeAuth } from '@vergeinfosoft/react';

function App() {
  return (
    <VergeAuth 
      config={{
        apiBaseUrl: '/api',
        authEndpoint: '/auth/me',
        loginUrl: 'https://app.vergeauth.in/login',
        logoutUrl: '/auth/logout',
        redirectUrl: window.location.origin
      }}
      callbackPath="/auth/callback"
    >
      <YourApp />
    </VergeAuth>
  );
}

Environment Variables

Set these in your .env file:

VITE_VERGEAUTH_LOGIN_URL=https://app.vergeauth.in/login

Advanced Usage

Using Individual Components

If you need more control, you can use the individual components:

import { AuthProvider, useAuth, ProtectedRoute } from '@vergeinfosoft/react';
import { BrowserRouter, Routes, Route } from 'react-router-dom';

function App() {
  return (
    <AuthProvider>
      <BrowserRouter>
        <Routes>
          <Route path="/auth/callback" element={<AuthCallback />} />
          <Route path="/*" element={
            <ProtectedRoute>
              <YourApp />
            </ProtectedRoute>
          } />
        </Routes>
      </BrowserRouter>
    </AuthProvider>
  );
}

Permission-Based Route Protection

import { ProtectedRoute } from '@vergeinfosoft/react';

function Dashboard() {
  return (
    <ProtectedRoute requiredPermissions={['hrms-service:/api/dashboard/stats:get']}>
      <DashboardContent />
    </ProtectedRoute>
  );
}

Using the Auth Hook

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

function UserProfile() {
  const { isAuthenticated, loading, permissions, hasPermission, login, logout } = useAuth();

  if (loading) return <div>Loading...</div>;

  if (!isAuthenticated) {
    return <button onClick={login}>Login</button>;
  }

  return (
    <div>
      <h1>Welcome!</h1>
      <p>Permissions: {permissions.join(', ')}</p>
      {hasPermission('admin') && <button>Admin Panel</button>}
      <button onClick={logout}>Logout</button>
    </div>
  );
}

Require All Permissions

By default, ProtectedRoute requires ANY of the specified permissions. To require ALL:

<ProtectedRoute 
  requiredPermissions={['perm1', 'perm2']} 
  requireAll={true}
>
  <AdminPanel />
</ProtectedRoute>

Custom Fallback Path

<ProtectedRoute 
  requiredPermissions={['admin']} 
  fallbackPath="/unauthorized"
>
  <AdminPanel />
</ProtectedRoute>

API Reference

VergeAuth

Main wrapper component for one-line integration.

Props:

• children (ReactNode): Your application
• config? (VergeAuthConfig): Configuration object
• callbackPath? (string): Path for auth callback (default: /auth/callback)

AuthProvider

Provides auth context to your app.

Props:

• children (ReactNode): Child components
• config? (VergeAuthConfig): Configuration object

ProtectedRoute

Protects routes based on authentication and permissions.

Props:

• children (ReactNode): Protected content
• requiredPermissions? (string[]): Required permissions
• requireAll? (boolean): Require all permissions instead of any (default: false)
• fallbackPath? (string): Redirect path if unauthorized (default: /)

AuthCallback

Handles OAuth callback from Verge Auth.

Props:

• redirectPath? (string): Path to redirect after successful auth (default: /)

useAuth

Hook to access auth state and methods.

Returns:

• isAuthenticated (boolean | null): Authentication status
• loading (boolean): Loading state
• permissions (string[]): User permissions
• appBrandName (string | null): App brand name
• user (any): User data
• hasPermission(permission: string) (function): Check if user has permission
• hasAnyPermission(permissions: string[]) (function): Check if user has any of the permissions
• login() (function): Redirect to login
• logout() (function): Redirect to logout

Configuration

VergeAuthConfig

interface VergeAuthConfig {
  apiBaseUrl?: string;        // Default: '/api'
  authEndpoint?: string;      // Default: '/auth/me'
  loginUrl?: string;          // Default: from VITE_VERGEAUTH_LOGIN_URL
  logoutUrl?: string;         // Default: '/auth/logout'
  redirectUrl?: string;       // Default: current URL
}

How It Works

1. Auth Check: On mount, the SDK calls /api/auth/me to check authentication status
2. 403 Handling: A 403 response means the user is authenticated but lacks route permission
3. Login Redirect: Unauthenticated users are redirected to the Verge Auth login page
4. Callback Handling: After login, the callback route handles the OAuth code exchange
5. Permission Checks: Routes can be protected based on user permissions

Backend Requirements

Your backend must:

• Use the Verge Auth Python SDK with add_central_auth(app)
• Provide an /api/auth/me endpoint (handled automatically by the SDK)
• Handle OAuth code exchange at /api/?code= (handled automatically by the SDK)

Example: Full HRMS Integration

import { VergeAuth, ProtectedRoute, useAuth } from '@vergeinfosoft/react';

const PERMISSIONS = {
  DASHBOARD_GET: "hrms-service:/api/dashboard/stats:get",
  EMPLOYEES_GET: "hrms-service:/api/employees:get",
  ATTENDANCE_GET: "hrms-service:/api/attendance:get",
};

function App() {
  return (
    <VergeAuth>
      <Dashboard />
      <Employees />
      <Attendance />
    </VergeAuth>
  );
}

function Dashboard() {
  return (
    <ProtectedRoute requiredPermissions={[PERMISSIONS.DASHBOARD_GET]}>
      <DashboardContent />
    </ProtectedRoute>
  );
}

function Employees() {
  return (
    <ProtectedRoute requiredPermissions={[PERMISSIONS.EMPLOYEES_GET]}>
      <EmployeesContent />
    </ProtectedRoute>
  );
}

License

MIT

Support

For issues and questions, please contact Verge Infosoft support.