flutterfire-configure

name	flutterfire-configure
description	Use when adding Firebase to a Flutter project, running flutterfire configure, initializing Firebase in main.dart, or configuring multiple flavors.

FlutterFire Configure Skill

This skill defines how to correctly set up and configure Firebase for Flutter applications.

When to Use

Use this skill when:

• Adding Firebase to a Flutter project for the first time.
• Running flutterfire configure after adding a new Firebase service or platform.
• Initializing Firebase in main.dart.
• Setting up separate Firebase projects for multiple app flavors.

---

1. Prerequisites

Install the required tools:

npm install -g firebase-tools
firebase login
dart pub global activate flutterfire_cli

Minimum platform requirements:

• Android: API level 19 (KitKat) or higher
• Apple: iOS 11 or higher

---

2. Setup and Configuration

# From your Flutter project directory:
flutterfire configure

# Add the core Firebase package:
flutter pub add firebase_core

• Re-run flutterfire configure any time you add support for a new platform or start using a new Firebase service.
• For Android-specific services (Crashlytics, Performance Monitoring), the FlutterFire CLI automatically adds the required Gradle plugins.
• Rebuild with flutter run after adding new Firebase plugins.

---

3. Firebase Initialization

import 'package:firebase_core/firebase_core.dart';
import 'firebase_options.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(
    options: DefaultFirebaseOptions.currentPlatform,
  );
  runApp(const MyApp());
}

• Call WidgetsFlutterBinding.ensureInitialized() before Firebase initialization.
• Place Firebase initialization before any other Firebase service calls.
• Never modify firebase_options.dart manually — it is auto-generated.
• Commit firebase_options.dart to version control — it contains non-secret configuration identifiers.
• For Firebase Emulator Suite: await Firebase.initializeApp(demoProjectId: "demo-project-id").

---

4. Verification and Best Practices

After configuration, verify the setup is working:

1. Run flutter run and confirm the app launches without Firebase initialization errors.
2. Check the debug console for Firebase initialized successfully or similar confirmation.
3. Verify firebase_options.dart was generated with the correct project ID.

• Enable Firebase Analytics for optimal experience with Crashlytics, Remote Config, and other products.
• Use a consistent Firebase project across all platforms for data consistency.
• For iOS/macOS apps using certain Firebase services, add the Keychain Sharing capability in Xcode.
• Test the Firebase configuration with both debug and release builds.
• Check version compatibility between Flutter plugins and the underlying Firebase SDK.

---

5. Multiple App Flavors

Create separate Firebase projects per environment (development, staging, production):

flutterfire config \
  --project=flutter-app-dev \
  --out=lib/firebase_options_dev.dart \
  --ios-bundle-id=com.example.flutterApp.dev \
  --ios-out=ios/flavors/dev/GoogleService-Info.plist \
  --android-package-name=com.example.flutter_app.dev \
  --android-out=android/app/src/dev/google-services.json

Centralize Firebase initialization by flavor:

// firebase.dart
import 'package:firebase_core/firebase_core.dart';
import 'package:flutter/services.dart';
import 'package:flutter_app/firebase_options_prod.dart' as prod;
import 'package:flutter_app/firebase_options_stg.dart' as stg;
import 'package:flutter_app/firebase_options_dev.dart' as dev;

Future<void> initializeFirebaseApp() async {
  final firebaseOptions = switch (appFlavor) {
    'prod' => prod.DefaultFirebaseOptions.currentPlatform,
    'stg' => stg.DefaultFirebaseOptions.currentPlatform,
    'dev' => dev.DefaultFirebaseOptions.currentPlatform,
    _ => throw UnsupportedError('Invalid flavor: $appFlavor'),
  };
  await Firebase.initializeApp(options: firebaseOptions);
}

// main.dart
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await initializeFirebaseApp();
  runApp(const MainApp());
}

• Use appFlavor or environment variables to select the configuration at runtime.
• Import each flavor's config with namespace aliases (e.g., as dev).
• Use a helper script to automate multi-flavor configuration.

---

References

• Add Firebase to your Flutter app
• FlutterFire CLI