@ciscode/ui-authentication-kit

Production-ready authentication UI components for React applications

Complete authentication solution with built-in pages, RBAC support, and session management. Drop-in components that work with any backend API.

✨ Features

• 🔐 Pre-built Auth Pages - Login, Register, Password Reset, Profile
• 🛡️ RBAC Support - Role-based access control with permissions
• 🔄 Session Management - Automatic token refresh and expiration handling
• 🎨 Customizable - Headless components, bring your own styles
• ♿ Accessible - ARIA-compliant, keyboard navigation
• 🌍 i18n Ready - Multi-language support via @ciscode/ui-translate-core
• 📱 Responsive - Mobile-first design
• 🚀 TypeScript - Full type safety

📦 Installation

npm install @ciscode/ui-authentication-kit
# or
yarn add @ciscode/ui-authentication-kit
# or
pnpm add @ciscode/ui-authentication-kit

Peer Dependencies

npm install react react-dom react-router-dom axios jwt-decode react-cookie lucide-react @ciscode/ui-translate-core

🚀 Quick Start

1. Wrap your app with AuthProvider

import{AuthProvider}from'@ciscode/ui-authentication-kit';import{BrowserRouter}from'react-router-dom';functionApp(){return(<BrowserRouter><AuthProviderconfig={{apiUrl: 'https://api.example.com',loginPath: '/auth/login',registerPath: '/auth/register',profilePath: '/auth/profile',logoutPath: '/auth/logout',redirectAfterLogin: '/dashboard',redirectAfterLogout: '/',}}>{/* Your app routes */}</AuthProvider></BrowserRouter>);}

2. Use authentication state

import{useAuthState}from'@ciscode/ui-authentication-kit';functionDashboard(){const{ user, isAuthenticated, logout }=useAuthState();if(!isAuthenticated){return<div>Please log in</div>;}return(<div><h1>Welcome, {user?.name}!</h1><buttononClick={logout}>Logout</button></div>);}

3. Protect routes with permissions

import{RequirePermissions}from'@ciscode/ui-authentication-kit';functionAdminPanel(){return(<RequirePermissionsfallbackpermessions={['admin.view','admin.edit']}fallbackRoles={['super-admin']}redirectTo="/unauthorized"><div>Admin Content</div></RequirePermissions>);}

📚 Documentation

• API Reference - Complete API documentation
• Examples - Integration examples
• Styling Guide - Customization guide
• Accessibility - A11y patterns
• Migration Guide - Upgrade guides
• Architecture - Project structure
• Release Guide - Release workflow

🧪 Testing

• Tests are centralized under the tests/ folder.
• Vitest is configured with jsdom and a global setup in tests/setup.ts.
• Run tests: npm test
• Run coverage: npm run test:cov

Folder layout:

tests/
components/
context/
hooks/
utils/
setup.ts

🎯 Key Components

Component	Description
AuthProvider	Root provider for authentication state and routing
ProfilePage	User profile management UI
RequirePermissions	Permission-based route guard
RbacProvider	Role-based access control context

🪝 Core Hooks

Hook	Description
useAuthState()	Access auth state (user, isAuthenticated, login, logout)
useHasRole(role)	Check if user has a specific role
useHasModule(module)	Check if user has access to a module
useCan(permission)	Check if user has a permission
useGrant()	Access RBAC grant management

🔐 RBAC Example

import{RbacProvider,useHasRole,useCan}from'@ciscode/ui-authentication-kit';functionApp(){return(<RbacProvider><Dashboard/></RbacProvider>);}functionDashboard(){constisAdmin=useHasRole('admin');constcanEditUsers=useCan('users.edit');return(<div>{isAdmin&&<AdminPanel/>}{canEditUsers&&<EditButton/>}</div>);}

🌐 Internationalization

The kit integrates with @ciscode/ui-translate-core for multi-language support:

import{TranslateProvider}from'@ciscode/ui-translate-core';<TranslateProviderlocale="en"translations={translations}><AuthProviderconfig={config}><App/></AuthProvider></TranslateProvider>;

🛠️ Development

# Install dependencies
npm install
# Build the library
npm run build
# Run tests
npm test# Run tests with coverage
npm run test:cov
# Type check
npm run typecheck
# Lint
npm run lint
# Format code
npm run format:write

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

1. Fork the repository
2. Create a feature branch from develop
3. Make your changes with tests
4. Submit a PR to develop

📄 License

ISC © CISCODE

🔗 Links

• GitHub Repository
• NPM Package
• Report Issues

📊 Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

🙏 Acknowledgments

Built with modern React patterns and best practices. Designed for enterprise applications.