flutterfire-configure

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