Package Exports
- @skylabs-digital/react-identity-access
Readme
React Identity Access
A powerful, modern authentication and authorization library for React applications. Built with TypeScript, featuring role-based access control, permission management, Magic Link authentication, and seamless integration with React applications.
๐ Features
- ๐ Secure Authentication - JWT-based authentication with automatic token refresh
- โจ Magic Link Authentication - Passwordless authentication via email with automatic verification
- ๐ง Flexible Login - Support for both email and phone number authentication
- ๐ฅ Role-Based Access Control - Granular permission system with role hierarchy
- ๐ก๏ธ Protected Components - Easy-to-use components for conditional rendering
- ๐ฑ Multi-Tenant Support - Built-in support for multi-tenant applications
- ๐ฏ TypeScript First - Full TypeScript support with comprehensive type definitions
- โก Modern React - Built with React hooks and context for optimal performance
- ๐ Session Management - Automatic session handling and token refresh
- ๐จ Feature Flags - Built-in feature flag management
- ๐ณ Subscription Management - Integrated billing and subscription handling
๐ฆ Installation
npm install @skylabs-digital/react-identity-access
# or
yarn add @skylabs-digital/react-identity-access
# or
pnpm add @skylabs-digital/react-identity-access
๐โโ๏ธ Quick Start
1. Setup Providers
Wrap your application with the required providers:
import {
AppProvider,
TenantProvider,
AuthProvider
} from '@skylabs-digital/react-identity-access';
function App() {
return (
<AppProvider
config={{
baseUrl: 'https://your-api.com',
appId: 'your-app-id',
}}
>
<TenantProvider
config={{
tenantMode: 'selector', // 'subdomain', 'selector', or 'fixed'
selectorParam: 'tenant',
}}
>
<AuthProvider>
{/* Your app components */}
</AuthProvider>
</TenantProvider>
</AppProvider>
);
}
2. Traditional Authentication
import { useAuth } from '@skylabs-digital/react-identity-access';
function LoginComponent() {
const { login, logout, sessionManager } = useAuth();
const user = sessionManager.getUser();
const handleLogin = async () => {
try {
// Supports both email and phone number
await login('user@example.com', 'password'); // Email
// await login('+1234567890', 'password'); // Phone
} catch (error) {
console.error('Login failed:', error);
}
};
return (
<div>
{user ? (
<div>
<p>Welcome, {user.name}!</p>
<button onClick={logout}>Logout</button>
</div>
) : (
<button onClick={handleLogin}>Login</button>
)}
</div>
);
}
3. Magic Link Authentication
import {
MagicLinkForm,
MagicLinkVerify,
useAuth
} from '@skylabs-digital/react-identity-access';
import { useNavigate } from 'react-router-dom';
// Send Magic Link
function MagicLinkLogin() {
const navigate = useNavigate();
const handleSuccess = (response) => {
console.log('Magic link sent successfully!');
};
return (
<MagicLinkForm
frontendUrl="https://yourapp.com"
onSuccess={handleSuccess}
onLoginClick={() => navigate('/login')}
onSignupClick={() => navigate('/signup')}
/>
);
}
// Verify Magic Link (at /magic-link/verify route)
function MagicLinkVerifyPage() {
const navigate = useNavigate();
const handleSuccess = (data) => {
console.log('Magic link verified!', data);
navigate('/dashboard');
};
const handleError = (error) => {
console.error('Verification failed:', error);
};
return (
<MagicLinkVerify
onSuccess={handleSuccess}
onError={handleError}
onBackToLogin={() => navigate('/login')}
autoRedirectDelay={3000}
/>
);
}
4. Protect Components
import { Protected } from '@skylabs-digital/react-identity-access';
function AdminPanel() {
return (
<Protected
requiredPermissions={['admin:read', 'users:manage']}
fallback={<div>Access denied</div>}
>
<div>Admin content here</div>
</Protected>
);
}
๐งฉ Pre-built Components
The library includes ready-to-use form components with full customization support:
Authentication Forms
import {
LoginForm,
SignupForm,
MagicLinkForm,
MagicLinkVerify,
PasswordRecoveryForm
} from '@skylabs-digital/react-identity-access';
// Login Form (supports email/phone + password)
<LoginForm
onSuccess={(user) => console.log('Logged in:', user)}
onForgotPasswordClick={() => navigate('/forgot-password')}
onSignupClick={() => navigate('/signup')}
onMagicLinkClick={() => navigate('/magic-link')}
showMagicLinkOption={true}
/>
// Signup Form
<SignupForm
onSuccess={(user) => console.log('Signed up:', user)}
onLoginClick={() => navigate('/login')}
onMagicLinkClick={() => navigate('/magic-link')}
showMagicLinkOption={true}
/>
// Magic Link Form
<MagicLinkForm
frontendUrl="https://yourapp.com"
onSuccess={() => console.log('Magic link sent!')}
onLoginClick={() => navigate('/login')}
onSignupClick={() => navigate('/signup')}
/>
// Magic Link Verification
<MagicLinkVerify
onSuccess={(data) => navigate('/dashboard')}
onError={(error) => console.error(error)}
onBackToLogin={() => navigate('/login')}
/>
// Password Recovery
<PasswordRecoveryForm
onSuccess={() => console.log('Recovery email sent!')}
onBackToLogin={() => navigate('/login')}
/>
Customization
All components support full customization of copy, styles, and icons:
<LoginForm
copy={{
title: 'Welcome Back',
submitButton: 'Sign In',
usernameLabel: 'Email or Phone',
}}
styles={{
container: { backgroundColor: '#f8f9fa' },
button: { backgroundColor: '#007bff' },
}}
icons={{
showPassword: <CustomEyeIcon />,
hidePassword: <CustomEyeOffIcon />,
}}
/>
๐๏ธ Architecture
Core Providers
- AppProvider - Application configuration and context
- TenantProvider - Multi-tenant configuration and management
- AuthProvider - Authentication and session management
- FeatureFlagProvider - Feature flag management
- SubscriptionProvider - Billing and subscription handling
Permission System
The library uses a resource-action permission format:
resource:action
Examples:
users:read
- Read user dataproducts:write
- Create/update productsadmin:*
- All admin permissionsreports:read
- View reports
๐ Documentation
๐ฎ Demo Application
A complete demo application is included in the example/
directory. To run it:
cd example
yarn install
yarn start
The demo showcases:
- Traditional Authentication - Email/phone + password login
- Magic Link Authentication - Passwordless login with automatic verification
- User Registration - Signup with email/phone support
- Password Recovery - Reset password functionality
- Role-based Dashboard - Different views based on user roles
- Permission Testing - Interactive permission system testing
- Protected Routes - Route-level access control
- Feature Flag Usage - Dynamic feature toggling
- Multi-tenant Support - Tenant switching and management
๐ ๏ธ Development
Prerequisites
- Node.js 18+
- yarn (recommended) or npm
Setup
# Clone the repository
git clone https://github.com/skylabs-digital/react-identity-access.git
cd react-identity-access
# Install dependencies
yarn install
# Build the library
yarn build
# Run tests
yarn test
# Run CI pipeline
yarn ci
# Start example app
cd example && yarn start
Project Structure
react-identity-access/
โโโ src/ # Library source code
โ โโโ components/ # React components (forms, guards, etc.)
โ โโโ providers/ # Context providers (Auth, Tenant, etc.)
โ โโโ services/ # API services and HTTP client
โ โโโ types/ # TypeScript definitions
โ โโโ index.ts # Main export
โโโ example/ # Demo application
โโโ docs/ # Documentation
โโโ dist/ # Built library
โโโ package.json
๐ง Configuration
Environment Variables
REACT_APP_BASE_URL=https://your-api.com
REACT_APP_ID=your-app-id
REACT_APP_TENANT_MODE=subdomain
Provider Configuration
// AppProvider Config
interface AppConfig {
baseUrl: string; // API base URL
appId: string; // Application identifier
apiTimeout?: number; // Request timeout (default: 30000)
retryAttempts?: number; // Retry attempts (default: 3)
}
// TenantProvider Config
interface TenantConfig {
tenantMode: 'subdomain' | 'selector' | 'fixed';
selectorParam?: string; // For 'selector' mode
fixedTenantSlug?: string; // For 'fixed' mode
initialTenant?: string; // Initial tenant value
}
๐งช Testing
The library includes comprehensive tests:
# Run all tests
yarn test
# Run tests in watch mode
yarn test:watch
# Run tests with coverage
yarn test:coverage
๐ Performance
- Tree-shakable - Only import what you need
- Lazy loading - Components load on demand
- Optimized re-renders - Minimal React re-renders
- Caching - Intelligent caching of API responses
๐ Security
- JWT tokens with automatic refresh
- Secure storage of sensitive data
- CSRF protection built-in
- Permission validation on both client and server
- Audit logging for security events
๐ Browser Support
- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+
๐ License
MIT License - see LICENSE file for details.
๐ค Contributing
We welcome contributions! Please see our Contributing Guide for details.
๐ Support
- ๐ง Email: support@skylabs.com
- ๐ฌ Discord: Join our community
- ๐ Issues: GitHub Issues
- ๐ Docs: Documentation
๐ฏ Roadmap
- Magic Link Authentication - Passwordless authentication via email โ
- Email/Phone Login Support - Flexible authentication methods โ
- Pre-built Form Components - Ready-to-use authentication forms โ
- Multi-tenant Architecture - Separate App and Tenant providers โ
- OAuth 2.0 / OpenID Connect - Social login integration
- Multi-factor Authentication - SMS/TOTP support
- Advanced Audit Logging - Comprehensive security tracking
- GraphQL Integration - GraphQL API support
- React Native Support - Mobile app integration
- SSR/Next.js Optimization - Server-side rendering support
- Biometric Authentication - WebAuthn/FIDO2 support
Made with โค๏ธ by Skylabs Digital