@frank-auth/react

A comprehensive, highly configurable React authentication UI library for the Frank Auth multi-tenant SaaS platform.

🌟 Features

• 🎨 Highly Customizable: Server-driven configuration with complete theme control
• 🏢 Multi-Tenant: Built-in organization management and switching
• 👥 Three-Tier Users: Support for Internal, External, and End Users
• 🔐 Advanced Security: MFA, Passkeys, OAuth, Magic Links
• 🌍 Internationalization: 10+ languages with RTL support
• ♿ Accessibility: WCAG 2.1 AA compliant
• 📱 Responsive: Mobile-first design
• ⚡ Performance: Tree-shaking, lazy loading, optimized bundles
• 🎯 TypeScript: Full type safety and IntelliSense
• 🔧 Framework Agnostic: Works with Next.js, Remix, Vite, and more

🚀 Quick Start

Installation

1npm install @frank-auth/react
2# or
3yarn add @frank-auth/react
4# or
5pnpm add @frank-auth/react

Basic Setup

1import { FrankAuthProvider, SignIn, UserButton } from '@frank-auth/react';
2
3function App() {
4  return (
5    <FrankAuthProvider publishableKey="pk_test_...">
6      <div className="app">
7        <nav>
8          <UserButton />
9        </nav>
10        <main>
11          <SignIn />
12        </main>
13      </div>
14    </FrankAuthProvider>
15  );
16}

Advanced Setup with Configuration

1import { 
2  FrankAuthProvider, 
3  SignIn, 
4  UserButton,
5  createFrankAuthConfig 
6} from '@frank-auth/react';
7
8const config = createFrankAuthConfig({
9  appearance: {
10    theme: 'auto',
11    colors: {
12      primary: '#6366f1',
13      background: '#ffffff',
14      foreground: '#0f172a',
15    },
16    elements: {
17      formButtonPrimary: 'bg-indigo-600 hover:bg-indigo-700',
18      card: 'shadow-xl border-2 border-indigo-100',
19    },
20  },
21  authentication: {
22    methods: ['email', 'oauth', 'passkey'],
23    mfa: {
24      enabled: true,
25      methods: ['totp', 'sms'],
26    },
27    oauth: {
28      providers: [
29        { provider: 'google', enabled: true },
30        { provider: 'github', enabled: true },
31      ],
32    },
33  },
34  organization: {
35    enabled: true,
36    allowInvitations: true,
37    maxMembers: 50,
38  },
39});
40
41function App() {
42  return (
43    <FrankAuthProvider 
44      publishableKey="pk_test_..."
45      config={config}
46      onAuthEvent={(event) => {
47        console.log('Auth event:', event);
48      }}
49    >
50      <SignIn mode="modal" />
51      <UserButton showProfile showOrganization />
52    </FrankAuthProvider>
53  );
54}

🎯 Component Examples

Authentication Components

SignIn Component

1import { SignIn } from '@frank-auth/react';
2
3// Basic usage
4<SignIn />
5
6// Modal mode
7<SignIn mode="modal" />
8
9// Custom appearance
10<SignIn 
11  appearance={{
12    elements: {
13      formButtonPrimary: 'bg-blue-600 hover:bg-blue-700',
14      card: 'rounded-2xl shadow-2xl',
15    }
16  }}
17/>
18
19// With custom handlers
20<SignIn 
21  onSignInSuccess={(user) => {
22    console.log('Welcome back!', user);
23    // Custom redirect or action
24  }}
25  onSignInError={(error) => {
26    console.error('Sign in failed:', error);
27    // Custom error handling
28  }}
29/>
30
31// Limited authentication methods
32<SignIn 
33  allowedMethods={['email', 'oauth']}
34  redirectAfterSignIn="/dashboard"
35/>

SignUp Component

1import { SignUp } from '@frank-auth/react';
2
3// Basic usage
4<SignUp />
5
6// With custom fields
7<SignUp 
8  customFields={[
9    {
10      id: 'company',
11      name: 'Company Name',
12      type: 'text',
13      required: true,
14    },
15    {
16      id: 'role',
17      name: 'Role',
18      type: 'select',
19      options: [
20        { value: 'developer', label: 'Developer' },
21        { value: 'designer', label: 'Designer' },
22        { value: 'manager', label: 'Manager' },
23      ],
24    },
25  ]}
26/>

UserButton Component

1import { UserButton } from '@frank-auth/react';
2
3// Basic usage
4<UserButton />
5
6// With custom actions
7<UserButton 
8  customActions={[
9    {
10      label: 'Settings',
11      action: () => navigate('/settings'),
12      icon: <SettingsIcon />,
13    },
14    {
15      label: 'Billing',
16      action: () => navigate('/billing'),
17      icon: <CreditCardIcon />,
18    },
19  ]}
20/>
21
22// Show specific sections
23<UserButton 
24  showProfile={true}
25  showOrganization={true}
26  showSessions={true}
27/>

Organization Components

Organization Switcher

1import { OrganizationSwitcher } from '@frank-auth/react';
2
3// Basic usage
4<OrganizationSwitcher />
5
6// With creation and switching
7<OrganizationSwitcher 
8  allowCreation={true}
9  allowSwitching={true}
10  showMembers={true}
11/>
12
13// Custom appearance
14<OrganizationSwitcher 
15  appearance={{
16    elements: {
17      organizationSwitcher: 'rounded-lg border-2',
18    }
19  }}
20/>

Organization Profile

1import { OrganizationProfile } from '@frank-auth/react';
2
3// Full organization management
4<OrganizationProfile 
5  showMembers={true}
6  showSettings={true}
7  showBilling={true}
8/>

🎨 Customization

Theme Configuration

1const customTheme = {
2  name: 'custom-theme',
3  colors: {
4    primary: '#8b5cf6',
5    secondary: '#06b6d4',
6    background: '#fafafa',
7    foreground: '#18181b',
8    muted: '#f4f4f5',
9    accent: '#f59e0b',
10    destructive: '#ef4444',
11    border: '#e4e4e7',
12    input: '#ffffff',
13    ring: '#8b5cf6',
14    success: '#10b981',
15    warning: '#f59e0b',
16    error: '#ef4444',
17  },
18  typography: {
19    fontFamily: 'Inter, -apple-system, sans-serif',
20    fontSize: {
21      xs: '0.75rem',
22      sm: '0.875rem',
23      base: '1rem',
24      lg: '1.125rem',
25      xl: '1.25rem',
26      '2xl': '1.5rem',
27      '3xl': '1.875rem',
28    },
29  },
30  layout: {
31    borderRadius: '0.75rem',
32    spacing: {
33      xs: '0.25rem',
34      sm: '0.5rem',
35      md: '1rem',
36      lg: '1.5rem',
37      xl: '3rem',
38    },
39  },
40};
41
42<FrankAuthProvider 
43  publishableKey="pk_test_..."
44  config={{
45    appearance: {
46      theme: customTheme,
47    }
48  }}
49>
50  {/* Your app */}
51</FrankAuthProvider>

Component Overrides

1import { FrankAuthProvider } from '@frank-auth/react';
2import { CustomSignIn, CustomUserButton } from './custom-components';
3
4<FrankAuthProvider 
5  publishableKey="pk_test_..."
6  config={{
7    components: {
8      SignIn: CustomSignIn,
9      UserButton: CustomUserButton,
10    }
11  }}
12>
13  {/* Your app */}
14</FrankAuthProvider>

CSS-in-JS Customization

1const config = {
2  appearance: {
3    elements: {
4      // Form elements
5      formButtonPrimary: 'bg-gradient-to-r from-purple-500 to-pink-500 hover:from-purple-600 hover:to-pink-600 text-white font-semibold py-2 px-4 rounded-lg shadow-lg transform transition hover:scale-105',
6      formFieldInput: 'border-2 border-gray-200 focus:border-purple-500 rounded-lg px-3 py-2 transition-colors',
7      formFieldLabel: 'text-sm font-medium text-gray-700 mb-1',
8      
9      // Cards
10      card: 'bg-white/80 backdrop-blur-sm border border-gray-200 rounded-2xl shadow-xl',
11      cardHeader: 'border-b border-gray-100 p-6',
12      cardBody: 'p-6',
13      
14      // Modal
15      modalOverlay: 'fixed inset-0 bg-black/50 backdrop-blur-sm',
16      modalContent: 'bg-white rounded-2xl shadow-2xl max-w-md w-full mx-4',
17      
18      // User interface
19      userButton: 'flex items-center space-x-2 px-3 py-2 rounded-lg hover:bg-gray-100 transition-colors',
20      organizationSwitcher: 'border border-gray-200 rounded-lg p-2 hover:bg-gray-50',
21    },
22    variables: {
23      '--frank-auth-primary': '#8b5cf6',
24      '--frank-auth-radius': '0.75rem',
25      '--frank-auth-shadow': '0 10px 25px -5px rgba(0, 0, 0, 0.1)',
26    },
27  },
28};

🔧 Hooks Usage

useAuth Hook

1import { useAuth } from '@frank-auth/react';
2
3function MyComponent() {
4  const { 
5    isLoaded, 
6    isSignedIn, 
7    user, 
8    signOut,
9    organization,
10    switchOrganization 
11  } = useAuth();
12
13  if (!isLoaded) {
14    return <div>Loading...</div>;
15  }
16
17  if (!isSignedIn) {
18    return <div>Please sign in</div>;
19  }
20
21  return (
22    <div>
23      <h1>Welcome, {user.firstName}!</h1>
24      <p>Organization: {organization?.name}</p>
25      <button onClick={() => signOut()}>
26        Sign Out
27      </button>
28    </div>
29  );
30}

useOrganization Hook

1import { useOrganization } from '@frank-auth/react';
2
3function OrganizationDashboard() {
4  const { 
5    organization, 
6    members, 
7    invitations,
8    isAdmin,
9    inviteMember,
10    removeMember 
11  } = useOrganization();
12
13  const handleInvite = async (email: string, role: string) => {
14    try {
15      await inviteMember({ email, role });
16      toast.success('Invitation sent!');
17    } catch (error) {
18      toast.error('Failed to send invitation');
19    }
20  };
21
22  return (
23    <div>
24      <h1>{organization.name}</h1>
25      <p>{members.length} members</p>
26      
27      {isAdmin && (
28        <button onClick={() => handleInvite('user@example.com', 'member')}>
29          Invite Member
30        </button>
31      )}
32    </div>
33  );
34}

usePermissions Hook

1import { usePermissions } from '@frank-auth/react';
2
3function AdminPanel() {
4  const { hasPermission, hasRole, checkPermission } = usePermissions();
5
6  const canManageUsers = hasPermission('users:write');
7  const isAdmin = hasRole('admin');
8  const canDeletePosts = checkPermission('posts:delete', { resourceId: 'post-123' });
9
10  return (
11    <div>
12      {canManageUsers && (
13        <button>Manage Users</button>
14      )}
15      
16      {isAdmin && (
17        <button>Admin Settings</button>
18      )}
19      
20      {canDeletePosts && (
21        <button>Delete Post</button>
22      )}
23    </div>
24  );
25}

🌐 Multi-Tenant Examples

Organization-Specific Branding

1// This configuration is automatically loaded from your Frank Auth backend
2// based on the current organization context
3
4function App() {
5  return (
6    <FrankAuthProvider 
7      publishableKey="pk_test_..."
8      organizationId="org_acme_corp"
9      onConfigLoad={(serverConfig) => {
10        // Server config includes organization-specific branding
11        console.log('Organization theme:', serverConfig.theme);
12        console.log('Organization logo:', serverConfig.branding.logo);
13      }}
14    >
15      <SignIn />
16    </FrankAuthProvider>
17  );
18}

Dynamic User Type Handling

1import { useAuth, configureForUserType } from '@frank-auth/react';
2
3function AppWrapper() {
4  const { user } = useAuth();
5  
6  // Configure based on user type
7  const config = configureForUserType(user?.type || 'end-users', {
8    appearance: {
9      theme: user?.type === 'internal' ? 'dark' : 'light',
10    },
11  });
12
13  return (
14    <FrankAuthProvider 
15      publishableKey="pk_test_..."
16      config={config}
17    >
18      <App />
19    </FrankAuthProvider>
20  );
21}

🔐 Advanced Security Features

Multi-Factor Authentication

1import { useMfa } from '@frank-auth/react';
2
3function SecuritySettings() {
4  const { 
5    mfaEnabled, 
6    availableMethods, 
7    enableMfa, 
8    disableMfa,
9    generateBackupCodes 
10  } = useMfa();
11
12  const handleEnableMfa = async (method: 'totp' | 'sms') => {
13    try {
14      const qrCode = await enableMfa(method);
15      // Show QR code to user for TOTP setup
16    } catch (error) {
17      console.error('Failed to enable MFA:', error);
18    }
19  };
20
21  return (
22    <div>
23      <h2>Two-Factor Authentication</h2>
24      <p>Status: {mfaEnabled ? 'Enabled' : 'Disabled'}</p>
25      
26      {!mfaEnabled && (
27        <div>
28          <button onClick={() => handleEnableMfa('totp')}>
29            Enable Authenticator App
30          </button>
31          <button onClick={() => handleEnableMfa('sms')}>
32            Enable SMS
33          </button>
34        </div>
35      )}
36      
37      {mfaEnabled && (
38        <div>
39          <button onClick={generateBackupCodes}>
40            Generate Backup Codes
41          </button>
42          <button onClick={disableMfa}>
43            Disable MFA
44          </button>
45        </div>
46      )}
47    </div>
48  );
49}

Passkey Integration

1import { usePasskeys } from '@frank-auth/react';
2
3function PasskeySettings() {
4  const { 
5    passkeys, 
6    registerPasskey, 
7    removePasskey,
8    isSupported 
9  } = usePasskeys();
10
11  if (!isSupported) {
12    return <div>Passkeys are not supported in this browser</div>;
13  }
14
15  const handleRegister = async () => {
16    try {
17      await registerPasskey({ name: 'My Device' });
18      toast.success('Passkey registered successfully!');
19    } catch (error) {
20      toast.error('Failed to register passkey');
21    }
22  };
23
24  return (
25    <div>
26      <h2>Passkeys</h2>
27      <button onClick={handleRegister}>
28        Add Passkey
29      </button>
30      
31      <div className="mt-4">
32        {passkeys.map((passkey) => (
33          <div key={passkey.id} className="flex items-center justify-between p-3 border rounded">
34            <div>
35              <p className="font-medium">{passkey.name}</p>
36              <p className="text-sm text-gray-500">
37                Added {new Date(passkey.createdAt).toLocaleDateString()}
38              </p>
39            </div>
40            <button 
41              onClick={() => removePasskey(passkey.id)}
42              className="text-red-600 hover:text-red-800"
43            >
44              Remove
45            </button>
46          </div>
47        ))}
48      </div>
49    </div>
50  );
51}

🚀 Framework Integration

Next.js Integration

1// pages/_app.tsx
2import { FrankAuthProvider } from '@frank-auth/react';
3import type { AppProps } from 'next/app';
4
5export default function App({ Component, pageProps }: AppProps) {
6  return (
7    <FrankAuthProvider publishableKey={process.env.NEXT_PUBLIC_FRANK_AUTH_PUBLISHABLE_KEY!}>
8      <Component {...pageProps} />
9    </FrankAuthProvider>
10  );
11}
12
13// pages/dashboard.tsx
14import { RequireAuth } from '@frank-auth/react';
15
16export default function Dashboard() {
17  return (
18    <RequireAuth>
19      <div>
20        <h1>Dashboard</h1>
21        {/* Protected content */}
22      </div>
23    </RequireAuth>
24  );
25}

Remix Integration

1// app/root.tsx
2import { FrankAuthProvider } from '@frank-auth/react';
3
4export default function App() {
5  return (
6    <html>
7      <head>
8        <meta charSet="utf-8" />
9        <meta name="viewport" content="width=device-width,initial-scale=1" />
10      </head>
11      <body>
12        <FrankAuthProvider publishableKey={ENV.FRANK_AUTH_PUBLISHABLE_KEY}>
13          <Outlet />
14        </FrankAuthProvider>
15      </body>
16    </html>
17  );
18}

📱 Mobile and Responsive Design

All components are mobile-first and responsive by default:

1// Components automatically adapt to screen size
2<SignIn mode="card" /> // Becomes full-screen on mobile
3
4// Custom responsive behavior
5<UserButton 
6  className="hidden md:block" // Hide on mobile
7/>
8
9<UserButton 
10  className="md:hidden" // Show only on mobile
11  showProfile={false} // Simplified mobile view
12/>

🌍 Internationalization

1import { FrankAuthProvider } from '@frank-auth/react';
2
3const config = {
4  localization: {
5    defaultLocale: 'en',
6    supportedLocales: ['en', 'es', 'fr', 'de', 'pt', 'it', 'ja', 'ko', 'zh'],
7    customTranslations: {
8      'es': {
9        'sign_in': 'Iniciar Sesión',
10        'sign_up': 'Registrarse',
11        'welcome_back': 'Bienvenido de vuelta',
12      },
13    },
14  },
15};
16
17<FrankAuthProvider 
18  publishableKey="pk_test_..."
19  config={config}
20>
21  {/* Components will use Spanish translations */}
22</FrankAuthProvider>

🔧 Development and Debugging

Debug Mode

1<FrankAuthProvider 
2  publishableKey="pk_test_..."
3  config={{
4    advanced: {
5      debug: true, // Enable debug logging
6      telemetry: false, // Disable telemetry in development
7    }
8  }}
9>
10  <App />
11</FrankAuthProvider>

Dev Tools

1import { AuthDevTools } from '@frank-auth/react';
2
3function App() {
4  return (
5    <div>
6      {/* Your app */}
7      {process.env.NODE_ENV === 'development' && <AuthDevTools />}
8    </div>
9  );
10}

📚 API Reference

Configuration Options

Option	Type	Description
publishableKey	string	Your Frank Auth publishable key
organizationId	string	Current organization ID
appearance	AppearanceConfig	Theme and styling configuration
authentication	AuthenticationConfig	Authentication methods and settings
organization	OrganizationConfig	Organization features and settings
localization	LocalizationConfig	Language and locale settings
components	ComponentOverrides	Custom component overrides
advanced	AdvancedConfig	Advanced options and debugging

Component Props

All components accept these common props:

Prop	Type	Description
className	string	Additional CSS classes
appearance	Partial<AppearanceConfig>	Component-specific appearance
onSuccess	(result: any) => void	Success callback
onError	(error: Error) => void	Error callback

🤝 Migration from ClerkJS

Frank Auth React is designed to be API-compatible with ClerkJS for easy migration:

1// Before (ClerkJS)
2import { ClerkProvider, SignIn, UserButton } from '@clerk/nextjs';
3
4<ClerkProvider publishableKey="pk_test_...">
5  <SignIn />
6  <UserButton />
7</ClerkProvider>
8
9// After (Frank Auth)
10import { FrankAuthProvider, SignIn, UserButton } from '@frank-auth/react';
11
12<FrankAuthProvider publishableKey="pk_test_...">
13  <SignIn />
14  <UserButton />
15</FrankAuthProvider>

📄 License

MIT License - see the LICENSE file for details.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📞 Support

• 📧 Email: support@frankauth.com
• 💬 Discord: Join our community
• 📖 Documentation: docs.frankauth.com
• 🐛 Issues: GitHub Issues

---

Made with ❤️ by the Frank Auth team