Firebase Setup

• Use

  firebase_core

  for initialization — call

  Firebase.initializeApp()

  before

  runApp()

• Use

  flutterfire configure

  for platform-specific setup
• Use separate Firebase projects per flavor (see

  app-config

  skill)
• Register Firebase services via

  injectable

  for consistent DI

Authentication

• Use

  firebase_auth

  for user management
• Wrap all auth calls in an

  AuthRepository

  — no direct

  FirebaseAuth

  usage in BLoCs or UI
• Support email/password, Google Sign-In, and Apple Sign-In at minimum
• Handle auth state changes via

  FirebaseAuth.instance.authStateChanges()

  stream in

  AuthBloc

• Store auth tokens via

  flutter_secure_storage

  — never in

  SharedPreferences

  or source code
• Implement proper sign-out: clear local cache, navigate to login, dispose user-specific BLoCs

Firestore

• Use

  cloud_firestore

  for remote data persistence
• DataSources wrap all Firestore calls (

  get

  ,

  set

  ,

  update

  ,

  delete

  ,

  snapshots

  )
• Use typed model classes with

  fromFirestore

  /

  toFirestore

  factory methods
• Prefer

  .withConverter<T>()

  for type-safe collection references
• Use batch writes for multi-document operations — never multiple sequential writes
• Implement offline persistence (enabled by default on mobile)

Security Rules

• NEVER rely on client-side validation alone — enforce rules in Firestore Security Rules
• Default deny: start with

  allow read, write: if false;

  and open only what's needed
• Always validate

  request.auth != null

  for authenticated-only collections
• Test rules with the Firebase Emulator Suite before deploying

Push Notifications (FCM)

• Use

  firebase_messaging

  for push notifications
• Request notification permissions early but gracefully (explain value before requesting)
• Handle foreground, background, and terminated-state messages separately
• Store FCM token in Firestore user document for server-side targeting
• Re-register token on

  onTokenRefresh

  stream

Crashlytics

• Use

  firebase_crashlytics

  for crash reporting
• Enable in staging and production flavors only — disable in dev
• Record Flutter errors:

  FlutterError.onError = FirebaseCrashlytics.instance.recordFlutterFatalError

• Catch async errors via

  PlatformDispatcher.instance.onError

• Add custom keys for user context:

  Crashlytics.instance.setCustomKey('userId', id)

Analytics

• Use

  firebase_analytics

  for user behavior tracking
• Log meaningful events with descriptive names:

  analytics.logEvent(name: 'purchase_completed')

• Set user properties for segmentation:

  analytics.setUserProperty(name: 'plan', value: 'premium')

• Track screen views via

  FirebaseAnalyticsObserver

  in

  GoRouter

• NEVER log PII (emails, passwords, phone numbers) in analytics events

Remote Config

• Use

  firebase_remote_config

  for feature flags and A/B testing
• Set sensible defaults locally — app MUST work without Remote Config fetched
• Fetch and activate on app start with a timeout fallback
• Cache values and respect minimum fetch intervals to avoid throttling