Firebase Flavors

A Dart CLI tool for configuring Firebase for multiple Flutter flavors.

Features

Configures Firebase within your Flutter app for multiple flavors
- Registers apps in Firebase project
- Downloads Google config to flavor-based directories in Android and/or iOS dir
- Generates per-flavor firebase_options file
- Adds script to Xcode project to copy the correct GoogleServices-Info.plist file into build dir
Initialize with your current settings from Android and/or iOS project files
Customize package names, bundle IDs, output paths, and more

Installation

Global (Recommended)

dart pub global activate firebase_flavors

You can then run it from anywhere with:

dart run firebase_flavors [command]

Make sure your PATH includes the pub cache bin directory:

macOS/Linux: ~/.pub-cache/bin
Windows: %APPDATA%\Pub\Cache\bin

Local Development Dependency

Add this to your project's pubspec.yaml under dev_dependencies:

dart pub add dev:firebase_flavors

You can then run it from your project root with:

dart run firebase_flavors:firebase_flavors [command]

Prerequisites

Before using firebase_flavors, ensure you have the following installed:

FlutterFire CLI: Required for Firebase configuration
```
dart pub global activate flutterfire_cli
```
Ruby (for iOS configuration): Required for Xcode project manipulation
- macOS: Usually pre-installed
- Linux/Windows: Install Ruby
xcodeproj gem (for iOS configuration): Required for modifying Xcode projects
```
gem install xcodeproj
```
Flutter: Your Flutter project should be set up with flavors configured in your build.gradle (Android) or Xcode schemes (iOS)

Quick Start

1. Initialize Configuration

Run the init command in your Flutter project root:

firebase_flavors init

This command will:

Detect your app's flavors from Android Gradle files or iOS project files
Detect your base bundle ID and app name
Generate a firebase_flavors.yaml configuration file

2. Set Firebase Project IDs

You can set Firebase project IDs in two ways:

Option A: Use the set-project-ids command (Recommended)

This command provides multiple methods to set project IDs:

# Auto-detect from existing config files
firebase_flavors set-project-ids --from-files

# Interactive selection from Firebase CLI projects list
firebase_flavors set-project-ids --from-firebase

# Interactive prompts
firebase_flavors set-project-ids --interactive

# Or specify directly via command line
firebase_flavors set-project-ids --project-ids dev:your-dev-project-id,prod:your-prod-project-id

Option B: Edit Configuration Manually

Open firebase_flavors.yaml and update the Firebase project IDs for each flavor:

flavors:
  dev:
    firebaseProjectId: your-dev-project-id
    # ... other settings
  staging:
    firebaseProjectId: your-staging-project-id
    # ... other settings
  prod:
    firebaseProjectId: your-prod-project-id
    # ... other settings

3. Configure Firebase

Run the configure command to set up Firebase for your flavors:

firebase_flavors configure

This will configure all flavors, or you can specify flavors using a list:

firebase_flavors configure dev,staging

Commands

`init`

Initializes a new firebase_flavors.yaml configuration file.

firebase_flavors init [--force] [--config <path>]

Options:

--force: Overwrite existing configuration file
--config <path>: Specify custom config file path (default: firebase_flavors.yaml)

What it does:

Detects flavors from android/app/build.gradle or iOS project files
Detects base bundle ID from Android or iOS configuration
Detects app name from project files
Generates a YAML configuration file with detected values

`configure`

Configures Firebase for specified flavors.

firebase_flavors configure [flavor1,flavor2,...] [--skip-firebase] [--skip-xcode] [--config <path>]

Arguments:

flavor1,flavor2,...: Comma-separated list of flavors to configure (optional, defaults to all flavors)

Options:

--skip-firebase: Skip Firebase configuration (only set up Xcode scripts)
--skip-xcode: Skip Xcode run script setup (only configure Firebase)
--config <path>: Specify custom config file path (default: firebase_flavors.yaml)

What it does:

Runs flutterfire configure for each flavor
Downloads and places google-services.json files for Android
Downloads and places GoogleService-Info.plist files for iOS
Sets up Xcode run scripts to copy the correct iOS config file based on build configuration
Generates Dart options files (firebase_options_*.dart) for each flavor

`list`

Lists all configured flavors and their details.

firebase_flavors list [--config <path>]

Options:

--config <path>: Specify custom config file path (default: firebase_flavors.yaml)

What it shows:

App name and base bundle ID
Platform paths (Android source base, iOS Xcode project, etc.)
For each flavor:
- Firebase project ID
- Supported platforms
- Android package name and config file path
- iOS bundle ID and config file path
- Dart options output path

`set-project-ids`

Sets Firebase project IDs for flavors in the configuration file.

firebase_flavors set-project-ids [--from-files] [--from-firebase] [--interactive] [--project-ids <pairs>] [--config <path>]

Options:

--from-files: Auto-detect project IDs from existing google-services.json or GoogleService-Info.plist files
--from-firebase: Interactive selection from Firebase CLI projects list (requires Firebase CLI login)
--interactive: Prompt for project IDs interactively
--project-ids <pairs>: Comma-separated list of flavor:project-id pairs (e.g., dev:project-id-1,prod:project-id-2)
--config <path>: Specify custom config file path (default: firebase_flavors.yaml)

What it does:

Updates the firebaseProjectId field for each flavor in firebase_flavors.yaml
Supports multiple methods for setting project IDs:
- Auto-detection from existing config files
- Interactive selection from Firebase projects
- Interactive prompts
- Direct specification via command line
If no method is specified, defaults to interactive mode

Global Options

All commands support these global options:

--help, -h: Show help information
--verbose, -v: Show additional debug output
--version: Show tool version
--config <path>, -c: Specify custom config file path (default: firebase_flavors.yaml)

Configuration File Structure

The firebase_flavors.yaml file has the following structure:

# App-level configuration (required)
appName: MyApp
baseBundleId: com.example.app

# Android configuration (optional - all fields have defaults)
android:
  srcBase: android/app/src  # Optional, default: android/app/src

# iOS configuration (optional - all fields have defaults)
ios:
  xcodeprojPath: ios/Runner.xcodeproj  # Optional, default: ios/Runner.xcodeproj
  target: Runner  # Optional, default: Runner
  configBase: ios/Runner/Runner  # Optional, default: ios/Runner/Runner

# Flavor-specific configuration
flavors:
  dev:
    firebaseProjectId: my-dev-project-id  # Required
    androidPackageSuffix: .dev  # Optional, default: null (no suffix)
    dartOptionsOut: lib/firebase_options_dev.dart  # Optional, default: lib/firebase_options_{flavor}.dart
    androidSrcDir: dev  # Optional, default: {flavor}
    iosConfigDir: dev  # Optional, default: {flavor}
    platforms: android,ios  # Optional, default: null (all platforms)
    iosBundleSuffix: dev  # Optional, default: null (no suffix)
  
  prod:
    firebaseProjectId: my-prod-project-id  # Required
    androidPackageSuffix: ""  # Optional, empty string = no suffix (default: null)
    # All other fields are optional with defaults as shown above

Configuration Fields

Global Configuration

appName (required): Your app's display name
baseBundleId (required): Base bundle/package identifier (e.g., com.example.app)

Android Configuration (all optional)

android.srcBase (optional): Base directory for Android source files. Default: android/app/src

iOS Configuration (all optional)

ios.xcodeprojPath (optional): Path to your Xcode project file. Default: ios/Runner.xcodeproj
ios.target (optional): Xcode target name. Default: Runner
ios.configBase (optional): Base directory for iOS configuration files. Default: ios/Runner/Runner

Flavor Configuration

firebaseProjectId (required): Your Firebase project ID for this flavor
androidPackageSuffix (optional): Suffix to append to base bundle ID for Android (e.g., .dev, .staging). Default: null (no suffix). If provided without a leading dot, one will be added automatically
dartOptionsOut (optional): Path where the Dart options file will be generated. Default: lib/firebase_options_{flavor}.dart
androidSrcDir (optional): Directory name under android/srcBase where google-services.json will be placed. Default: {flavor} (the flavor name)
iosConfigDir (optional): Directory name under ios.configBase where GoogleService-Info.plist will be placed. Default: {flavor} (the flavor name)
platforms (optional): Comma-separated list of platforms (android, ios). If omitted or empty, all platforms are configured. Default: null (all platforms)
iosBundleSuffix (optional): Suffix to append to base bundle ID for iOS (e.g., .dev, .staging). Default: null (no suffix). If provided without a leading dot, one will be added automatically

Examples

Example 1: Basic Setup

# 1. Initialize
firebase_flavors init

# 2. Set Firebase project IDs (or edit firebase_flavors.yaml manually)
firebase_flavors set-project-ids --from-firebase

# 3. Configure all flavors
firebase_flavors configure

Example 2: Configure Specific Flavors

# Configure only dev and staging
firebase_flavors configure dev,staging

Example 3: Skip Xcode Setup

# Configure Firebase but skip Xcode run script setup
firebase_flavors configure --skip-xcode

Example 4: Custom Config File

# Use a custom configuration file
firebase_flavors init --config custom_config.yaml
firebase_flavors configure --config custom_config.yaml

Example 5: Verbose Output

# Get detailed debug information
firebase_flavors configure --verbose

Example 6: Set Project IDs from Files

# Auto-detect project IDs from existing config files
firebase_flavors set-project-ids --from-files

Example 7: Set Project IDs from Firebase CLI

# Select projects interactively from Firebase CLI
firebase_flavors set-project-ids --from-firebase

Example 8: Set Project IDs via Command Line

# Set project IDs directly
firebase_flavors set-project-ids --project-ids dev:my-dev-project,staging:my-staging-project,prod:my-prod-project

Project Structure

After configuration, your project structure will look like this:

your_flutter_project/
├── firebase_flavors.yaml
├── lib/
│   ├── firebase_options_dev.dart
│   ├── firebase_options_staging.dart
│   └── firebase_options_prod.dart
├── android/
│   └── app/
│       └── src/
│           ├── dev/
│           │   └── google-services.json
│           ├── staging/
│           │   └── google-services.json
│           └── prod/
│               └── google-services.json
└── ios/
    └── Runner/
        └── Runner/
            ├── dev/
            │   └── GoogleService-Info.plist
            ├── staging/
            │   └── GoogleService-Info.plist
            └── prod/
                └── GoogleService-Info.plist

Using in Your Flutter App

After configuration, use separate Dart entrypoints for each flavor, as recommended by Firebase. This allows you to specify which firebase_options_x.dart file to include per flavor, without needing conditional imports or extra build tools.

For example, create separate files in your lib/ directory:

lib/main_dev.dart

import 'package:flutter/widgets.dart';
import 'package:firebase_core/firebase_core.dart';
import 'firebase_options_dev.dart';

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

lib/main_staging.dart

import 'package:flutter/widgets.dart';
import 'package:firebase_core/firebase_core.dart';
import 'firebase_options_staging.dart';

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

lib/main_prod.dart

import 'package:flutter/widgets.dart';
import 'package:firebase_core/firebase_core.dart';
import 'firebase_options_prod.dart';

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

To run a specific flavor, provide the corresponding entrypoint with Flutter's -t (target) flag:

# Development flavor
flutter run -t lib/main_dev.dart

# Staging flavor
flutter run -t lib/main_staging.dart

# Production flavor
flutter run -t lib/main_prod.dart

Tip: This is the recommended approach for multi-flavor support. Each entrypoint statically imports the correct firebase_options_*.dart file for its flavor, avoiding runtime ambiguity and making builds more robust and predictable.

Troubleshooting

flutterfire CLI not found

Error: flutterfire CLI is not installed or not found on your PATH

Solution:

dart pub global activate flutterfire_cli
# Make sure ~/.pub-cache/bin is in your PATH

xcodeproj gem not found

Error: xcodeproj gem is not installed

Solution:

gem install xcodeproj

Configuration file not detected

Error: No project configuration detected, using defaults

Solution: The tool will use default values. You can manually edit firebase_flavors.yaml after initialization to match your project structure.

Firebase project ID not set

Error: firebaseProjectId is required

Solution: Make sure each flavor in firebase_flavors.yaml has a valid firebaseProjectId set.

Xcode script setup fails

Error: Issues with Xcode run script setup

Solution:

Ensure Ruby and xcodeproj gem are installed
Check that your Xcode project path is correct in the configuration
Try running with --skip-xcode to skip this step and set up manually

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is open source. Please check the repository for license information.

Support

For issues, questions, or contributions, please visit the GitHub repository.

Firebase Flavors

Features

Installation

Global (Recommended)

Local Development Dependency

Prerequisites

Quick Start

1. Initialize Configuration

2. Set Firebase Project IDs

3. Configure Firebase

Commands

init

configure

list

set-project-ids

Global Options

Configuration File Structure

Configuration Fields

Global Configuration

Android Configuration (all optional)

iOS Configuration (all optional)

Flavor Configuration

Examples

Example 1: Basic Setup

Example 2: Configure Specific Flavors

Example 3: Skip Xcode Setup

Example 4: Custom Config File

Example 5: Verbose Output

Example 6: Set Project IDs from Files

Example 7: Set Project IDs from Firebase CLI

Example 8: Set Project IDs via Command Line

Project Structure

Using in Your Flutter App

Troubleshooting

flutterfire CLI not found

xcodeproj gem not found

Configuration file not detected

Firebase project ID not set

Xcode script setup fails

Contributing

License

Support

Libraries

firebase_flavors package

`init`

`configure`

`list`

`set-project-ids`