@umituz/react-native-firebase


Comprehensive Firebase package for React Native applications using Firebase JS SDK (no native modules required). Built with Domain-Driven Design (DDD) architecture.

🚀 Quick Start

Read First: Before using this package, read the CONTRIBUTING.md for development guidelines and AI instructions.

$3

``bash
npm install @umituz/react-native-firebase firebase

Required peer dependencies


npm install expo-apple-authentication expo-crypto @umituz/react-native-storage
`

$3

1. Initialize Firebase once at app startup
2. Use hooks for authentication state
3. Use repositories for database operations
4. Follow module-specific guidelines in each README

📦 Modules

$3

Location: src/auth/README.md

Provides authentication functionality:
- Anonymous, Google, Apple, Email/Password authentication
- Auth state management with React hooks
- Account deletion and reauthentication
- Auth guards for protected routes

Key Strategy: Never use Firebase Auth SDK directly in UI. Always use the provided hooks and services.

$3

Location: src/firestore/README.md

Database operations with repository pattern:
- Base, Query, and Paginated repositories
- Quota management and tracking
- Middleware for caching and monitoring
- Request logging and analytics

Key Strategy: Always access Firestore through repositories. Never bypass the repository layer.

$3

Location: src/storage/README.md

File storage operations:
- Base64 and file uploads
- Single and batch deletion
- Metadata management

Key Strategy: Always clean up old files. Use organized path structures.

$3

Location: scripts/README.md

Backend utilities:
- User management and cleanup
- Firestore collection operations
- Storage file management

Key Strategy: Use for admin operations, not in client apps.

🏗️ Architecture

This package follows Domain-Driven Design (DDD) principles.

$3

`
├── domain/ # Business logic (entities, errors, value objects)
├── infrastructure/ # External dependencies (Firebase, APIs)
└── presentation/ # UI integration (React hooks, components)
`

$3

- Repository Pattern - Data access through repository abstractions
- Middleware Pattern - Cross-cutting concerns (logging, caching)
- Service Layer - Business logic encapsulation
- Factory Pattern - Object creation and initialization

✅ Required Practices

$3

1. Type Safety: Use TypeScript strict mode
2. Error Handling: Handle all errors appropriately
3. Documentation: Keep README files in sync with code
4. Testing: Write tests for new functionality
5. File Size: Keep files under 200 lines

$3

1. Use hooks (never Firebase SDK directly in UI)
2. Protect routes with auth guards
3. Handle auth state changes properly
4. Clean up auth listeners on unmount

$3

1. Always use repositories for data access
2. Use pagination for large datasets
3. Track quota usage with middleware
4. Create appropriate indexes in Firebase Console
5. Use query builders for complex queries

$3

1. Clean up old files before uploading new ones
2. Use organized path structures
3. Add metadata to files for tracking
4. Handle deletion errors gracefully

🚫 Forbidden Practices

$3

- ❌ Mixing architectural layers (e.g., infrastructure importing from domain)
- ❌ Bypassing repositories to access Firestore directly
- ❌ Using Firebase SDK directly in UI components
- ❌ Creating circular dependencies between modules
- ❌ Putting business logic in presentation layer

$3

- ❌ Files larger than 200 lines
- ❌ Duplicated code
- ❌ Using any type
- ❌ Magic numbers or strings (use constants)
- ❌ Hardcoded configuration values

$3

- ❌ Hardcoded credentials or API keys
- ❌ Console.log in production code
- ❌ Swallowing errors silently
- ❌ Ignoring TypeScript errors

🤖 For AI Agents

$3

1. READ the module-specific README first
2. FOLLOW existing patterns in the codebase
3. RESPECT architectural boundaries
4. CHECK file size limits (max 200 lines)
5. USE established utilities and services

$3

1. Search for similar existing functionality
2. Check if a utility already exists
3. Read the relevant module README
4. Understand the architectural layer

$3

1. Keep files under 200 lines
2. Follow TypeScript strict mode
3. Use proper naming conventions
4. Handle all errors
5. Add JSDoc comments for public APIs

📚 Documentation

- Development Guidelines - Must read before contributing
- Auth Module - Authentication strategies and rules
- Firestore Module - Database operations and patterns
- Storage Module - File storage guidelines
- Infrastructure - Core setup and configuration

🎯 Usage Strategies

$3

1. Initialize Firebase once at app startup
2. Use useFirebaseAuth hook for auth state
3. Use specific auth hooks for different providers
4. Protect routes with auth guards
5. Handle auth errors with user-friendly messages

$3

1. Create repositories extending base repository classes
2. Use pagination for large datasets
3. Register middleware for quota tracking
4. Use query builders for complex queries
5. Monitor quota usage regularly

$3

1. Use organized path structures (e.g., users/{userId}/avatar.jpg)
2. Delete old files before uploading new ones
3. Add metadata for tracking
4. Handle upload/deletion errors appropriately

🔧 Environment Setup

$3

`bash
EXPO_PUBLIC_FIREBASE_API_KEY=your-api-key
EXPO_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
EXPO_PUBLIC_FIREBASE_STORAGE_BUCKET=your-bucket
`

$3

1. Create Firebase project
2. Enable required services (Auth, Firestore, Storage)
3. Configure authentication providers
4. Set security rules for Firestore and Storage

📋 Module Documentation

Each module has comprehensive documentation including:
- Purpose and responsibilities
- Architecture overview
- Usage strategies
- Required practices
- Forbidden practices
- AI agent instructions

Read the module-specific README before working on that module.

🛠️ Development

$3

`bash
npm run typecheck
`

$3

`bash
npm run lint
`

$3

`bash
npm run build:scripts
``

📝 Contributing

1. Read CONTRIBUTING.md
2. Read module-specific README
3. Follow architectural patterns
4. Keep files under 200 lines
5. Update documentation if behavior changes
6. Ensure all tests pass

📄 License

MIT License - see LICENSE for details.

🆘 Support

- Issues: GitHub Issues
- Email: umit@umituz.com

---

Last Updated: 2025-01-08
Version: 1.13.58
Maintainer: Ümit UZ