Authentication service for React Native apps - Secure, type-safe, and production-ready. Provider-agnostic design with dependency injection, configurable validation, and comprehensive error handling.
npm install @umituz/react-native-authAuthentication service for React Native applications with secure, type-safe, and production-ready implementation.
---
Purpose: Provides comprehensive authentication solution for React Native apps with Domain-Driven Design architecture, supporting multiple authentication methods and providers.
When to Use:
- Building React Native apps requiring authentication
- Need multiple auth methods (email, social, anonymous)
- Want type-safe auth implementation
- Prefer DDD architecture
- Need production-ready auth solution
Package Location: /src
Documentation: See /src/[layer]/README.md for detailed documentation
---
SUPPORTED METHODS:
- Email/Password authentication
- Google OAuth integration
- Apple Sign-In (iOS)
- Anonymous user sessions
- Account upgrade (anonymous → registered)
DOMAIN-DRIVEN DESIGN LAYERS:
- Domain: Core business logic and entities
- Application: Use cases and interfaces
- Infrastructure: External integrations
- Presentation: UI components and hooks
---
NPM:
``bash`
npm install @umituz/react-native-auth
Yarn:
`bash`
yarn add @umituz/react-native-auth
REQUIRED PACKAGES:
- firebase: >= 11.0.0react
- : >= 18.2.0react-native
- : >= 0.74.0@tanstack/react-query
- : >= 5.0.0zustand
- : >= 4.0.0
EXTERNAL DEPENDENCIES:
- @umituz/react-native-firebase - Firebase integration@umituz/react-native-design-system
- - UI components
---
Rules:
- MUST create Firebase project
- MUST enable Authentication
- MUST enable Firestore (for user documents)
- MUST configure OAuth providers
MUST NOT:
- Skip Firebase console setup
- Use production keys in development
- Forget to enable required providers
Steps:
1. Create Firebase project at console.firebase.google.com
2. Enable Authentication
3. Enable Google Sign-In
4. Enable Apple Sign-In (for iOS)
5. Enable Firestore
6. Download config files
---
Location: src/domain/
Purpose: Core business logic and entities
CONTAINS:
- AuthUser entityUserProfile
- entityAuthConfig
- value objectAuthError
- hierarchy
Documentation: src/domain/README.md
---
Location: src/application/
Purpose: Use cases and interfaces
CONTAINS:
- Authentication ports
- User profile ports
- Account management ports
Documentation: src/application/README.md
---
Location: src/infrastructure/
Purpose: External integrations and implementations
CONTAINS:
- Firebase Auth service
- Firestore repositories
- Validation utilities
- Provider implementations
Documentation:
- src/infrastructure/README.md
-
---
Location: src/presentation/
Purpose: UI components and hooks
CONTAINS:
- React hooks for auth
- Pre-built components
- Screen components
- State management (Zustand)
Documentation:
- src/presentation/README.md
-
-
-
---
PRIMARY HOOK: useAuth
Location:
When to Use:
- Need authentication state
- Require user information
- Performing auth operations
- Checking auth status
Import Path:
`typescript`
import { useAuth } from '@umituz/react-native-auth';
Rules:
- MUST initialize AuthProvider before use
- MUST handle loading state
- MUST check auth readiness
- MUST handle errors appropriately
---
AVAILABLE COMPONENTS:
- LoginForm - Email/password loginRegisterForm
- - User registrationSocialLoginButtons
- - Google/Apple buttonsProfileSection
- - Profile displayAccountActions
- - Account management
Import Path:
`typescript`
import {
LoginForm,
RegisterForm,
SocialLoginButtons
} from '@umituz/react-native-auth';
Rules:
- MUST follow component documentation
- MUST provide required props
- MUST handle events appropriately
- MUST NOT override internal logic
---
iOS: ✅ Full support
- All authentication methods
- Apple Sign-In available
- Google Sign-In available
Android: ✅ Full support
- All authentication methods (except Apple)
- Google Sign-In available
Web: ✅ Full support
- All authentication methods (except Apple)
- Google Sign-In available
---
MUST:
- Validate all inputs
- Use HTTPS for all operations
- Implement proper error handling
- Follow Firebase security best practices
- Use secure token storage
- Validate tokens server-side
MUST NOT:
- Store tokens in AsyncStorage
- Log passwords or tokens
- Expose sensitive data in errors
- Skip validation
- Use HTTP for auth operations
---
PRINCIPLES:
- Business logic in domain layer
- Infrastructure concerns isolated
- Presentation layer UI-focused
- Application layer orchestrates
BENEFITS:
- Testable business logic
- Swappable providers
- Clear separation of concerns
- Maintainable codebase
---
Purpose: Comprehensive error handling throughout application.
Rules:
- MUST handle auth errors gracefully
- MUST show user-friendly messages
- MUST allow retry after failures
- MUST log errors for debugging
- MUST not expose sensitive data
Error Hierarchy:
- AuthError - Base error classValidationError
- - Input validation errorsAuthenticationError
- - Auth operation errorsNetworkError
- - Network issues
---
Purpose: Ensure data integrity and security.
Rules:
- MUST validate email format
- MUST validate password complexity
- MUST validate required fields
- MUST provide clear error messages
- MUST prevent invalid submissions
Validation Location: src/infrastructure/utils/AuthValidation.ts
---
Breaking Changes:
- See changelog for details
- Follow migration steps
- Update component props
- Update hook usage
Rules:
- MUST read migration guide
- MUST test thoroughly after upgrade
- MUST update dependencies
- MUST check deprecated features
---
Rules:
- MUST memoize expensive computations
- MUST minimize re-renders
- MUST optimize state updates
- MUST use efficient selectors
Constraints:
- Auth state single source of truth
- Minimal network requests
- Efficient validation checks
- Optimized component rendering
---
WHAT TO TEST:
- Domain logic and entities
- Validation utilities
- Hook behavior
- Component rendering
RULES:
- MUST test auth operations
- MUST test validation
- MUST test error handling
- MUST mock Firebase dependencies
---
RULES:
- MUST follow DDD principles
- MUST maintain type safety
- MUST update documentation
- MUST add tests for new features
- MUST follow existing patterns
MUST NOT:
- Break DDD layer boundaries
- Skip documentation
- Add code without tests
- Introduce breaking changes without major version bump
---
MIT License - See LICENSE file for details
---
MAIN README: This file
LAYER DOCUMENTATION:
- src/domain/README.md - Domain layer detailssrc/application/README.md
- - Application layer detailssrc/infrastructure/README.md
- - Infrastructure detailssrc/presentation/README.md` - Presentation layer details
-
COMPONENT/HOOK DOCUMENTATION:
- Each component has dedicated .md file
- Each hook has dedicated .md file
- Follows Strategy/Rules/Constraints format
- Read documentation first
- Check existing issues
- Review examples in docs
- Follow AI agent guidelines
---
See CHANGELOG.md for version history and changes.