Flutter Flavor Orchestrator 🎨 #

☕ Buy me a coffee on Ko-fi - If this package helps you, consider supporting my work!

A powerful, enterprise-grade build-time orchestrator for managing Flutter flavors, native configurations, and provisioning files across Android and iOS platforms.

✨ Features #

🎯 Multiple Flavor Management - Easily configure dev, staging, production, and custom flavors
📱 Cross-Platform Support - Automatically updates Android and iOS native files
🔧 Native File Manipulation - Intelligent modification of AndroidManifest.xml, build.gradle/build.gradle.kts, Info.plist, and more
🎨 Format Preservation - Maintains original indentation and structure in AndroidManifest.xml files
🔥 Firebase Integration - Automatic provisioning file management (google-services.json, GoogleService-Info.plist)
🏗️ Clean Architecture - Enterprise-level code quality with separation of concerns
🛡️ Safe Operations - Automatic backup and rollback on errors
📝 YAML Configuration - Simple, declarative configuration files
🔍 CLI Interface - Intuitive command-line tool with helpful output
✅ Validated - Built-in configuration validation and error handling
📚 Well Documented - Comprehensive documentation and examples

🚀 Installation #

Add flutter_flavor_orchestrator to your pubspec.yaml dev dependencies:

dev_dependencies:
  flutter_flavor_orchestrator: ^0.1.0

Then run:

flutter pub get

Activate the CLI tool globally (optional):

dart pub global activate flutter_flavor_orchestrator

⚡ Quick Start #

1. Create Configuration File #

Create a flavor_config.yaml file in your project root:

dev:
  bundle_id: com.example.myapp.dev
  app_name: MyApp Dev
  metadata:
    API_URL: https://dev-api.example.com
  provisioning:
    android_google_services: configs/dev/google-services.json
    ios_google_service: configs/dev/GoogleService-Info.plist

production:
  bundle_id: com.example.myapp
  app_name: MyApp
  metadata:
    API_URL: https://api.example.com
  provisioning:
    android_google_services: configs/production/google-services.json
    ios_google_service: configs/production/GoogleService-Info.plist

2. Apply a Flavor #

# From your project root
flutter pub run flutter_flavor_orchestrator apply --flavor dev

3. Build Your App #

flutter clean
flutter pub get
flutter build apk  # or flutter build ios

That's it! Your app is now configured for the dev flavor.

⚙️ Configuration #

Configuration File Location #

You can place your flavor configuration in either:

Dedicated file: flavor_config.yaml in your project root (recommended)
In pubspec.yaml: Under a flavor_config section

Configuration Options #

Each flavor supports the following configuration options:

Option	Type	Required	Description
`bundle_id`	String	✅	Bundle identifier (iOS) / Package name (Android)
`app_name`	String	✅	Display name of the application
`icon_path`	String	❌	Path to app icon assets
`metadata`	Map	❌	Custom key-value pairs to inject into manifests
`assets`	List	❌	Flavor-specific asset paths
`dependencies`	Map	❌	Flavor-specific dependency overrides
`provisioning`	Object	❌	Provisioning file configuration
`android_min_sdk_version`	Integer	❌	Android minimum SDK version
`android_target_sdk_version`	Integer	❌	Android target SDK version
`android_compile_sdk_version`	Integer	❌	Android compile SDK version
`ios_min_version`	String	❌	iOS minimum deployment target
`custom_gradle_config`	Map	❌	Custom Gradle configuration snippets
`custom_info_plist_entries`	Map	❌	Custom Info.plist entries

Provisioning Configuration #

provisioning:
  android_google_services: path/to/google-services.json
  ios_google_service: path/to/GoogleService-Info.plist
  additional_files:
    destination/path: source/path

Complete Example #

See example/flavor_config.yaml for a comprehensive configuration example.

🎮 CLI Usage #

The package provides a powerful command-line interface:

Apply Command #

Apply a flavor configuration to your project:

# Apply to both platforms
flutter_flavor_orchestrator apply --flavor dev

# Apply to Android only
flutter_flavor_orchestrator apply --flavor staging --platform android

# Apply to iOS only
flutter_flavor_orchestrator apply --flavor production --platform ios

# Enable verbose output
flutter_flavor_orchestrator apply --flavor dev --verbose

List Command #

List all available flavors:

flutter_flavor_orchestrator list

Info Command #

Display detailed information about a specific flavor:

flutter_flavor_orchestrator info --flavor production

Validate Command #

Validate all flavor configurations:

flutter_flavor_orchestrator validate

Help #

Display help information:

flutter_flavor_orchestrator --help

🔨 What Gets Modified #

Android #

When you apply a flavor, the following Android files are automatically updated:

`android/app/src/main/AndroidManifest.xml`

✏️ Package name (package attribute)
✏️ Application label (android:label)
✏️ Metadata entries (<meta-data> tags)
🎨 Preserves original formatting - Maintains exact indentation, whitespace, and structure

`android/app/build.gradle` or `android/app/build.gradle.kts`

✏️ Application ID (applicationId)
✏️ SDK versions (minSdkVersion, targetSdkVersion, compileSdkVersion)
✏️ Custom Gradle configuration
🔄 Supports both Groovy (.gradle) and Kotlin (.gradle.kts) build scripts

`android/app/google-services.json`

📋 Copied from configured path

iOS #

`ios/Runner/Info.plist`

✏️ Bundle display name (CFBundleDisplayName)
✏️ Bundle identifier (CFBundleIdentifier)
✏️ Minimum OS version (MinimumOSVersion)
✏️ Custom plist entries

`ios/Runner.xcodeproj/project.pbxproj`

✏️ Product bundle identifier (PRODUCT_BUNDLE_IDENTIFIER)
✏️ Deployment target (IPHONEOS_DEPLOYMENT_TARGET)

`ios/Runner/GoogleService-Info.plist`

📋 Copied from configured path

🏗️ Advanced Configuration #

Custom Gradle Configuration #

Inject custom Gradle snippets:

custom_gradle_config:
  defaultConfig: |
    buildConfigField "String", "API_URL", "\"https://api.example.com\""
    buildConfigField "boolean", "DEBUG_MODE", "false"
  buildTypes: |
    release {
        shrinkResources true
        minifyEnabled true
    }

Custom Info.plist Entries #

Add custom iOS configuration:

custom_info_plist_entries:
  NSAppTransportSecurity:
    NSAllowsArbitraryLoads: true
  UIBackgroundModes:
    - fetch
    - remote-notification
  ITSAppUsesNonExemptEncryption: false

Metadata Injection #

Add custom metadata to both platforms:

metadata:
  API_URL: https://api.example.com
  API_KEY: your_api_key
  FEATURE_FLAG_X: true
  MAX_RETRIES: 3

Android: Added as <meta-data> tags in AndroidManifest.xml

iOS: Added as custom entries in Info.plist

🏛️ Architecture #

The package follows Clean Architecture principles:

lib/
├── src/
│   ├── models/              # Data models
│   │   ├── flavor_config.dart
│   │   └── provisioning_config.dart
│   ├── processors/          # Platform processors
│   │   ├── android_processor.dart
│   │   └── ios_processor.dart
│   ├── utils/              # Utilities
│   │   ├── file_manager.dart
│   │   └── logger.dart
│   ├── config_parser.dart  # Configuration parsing
│   └── orchestrator.dart   # Main orchestrator
└── flutter_flavor_orchestrator.dart  # Public API

Key Components #

FlavorOrchestrator: Coordinates the entire process
ConfigParser: Parses and validates YAML configurations
AndroidProcessor: Handles Android-specific modifications
IosProcessor: Handles iOS-specific modifications
FileManager: Provides safe file operations with backup/rollback

📚 Examples #

Check out the example directory for a complete working example with:

✅ Multiple flavor configurations
✅ Firebase integration
✅ Custom metadata
✅ Platform-specific configurations
✅ Complete Flutter app

📖 API Documentation #

Programmatic Usage #

You can also use the package programmatically in your Dart code:

import 'package:flutter_flavor_orchestrator/flutter_flavor_orchestrator.dart';

void main() async {
  final orchestrator = FlavorOrchestrator(
    projectRoot: '/path/to/project',
    verbose: true,
  );

  // Apply a flavor
  final success = await orchestrator.applyFlavor(
    'dev',
    platforms: ['android', 'ios'],
  );

  // List flavors
  final flavors = await orchestrator.listFlavors();

  // Validate configurations
  final valid = await orchestrator.validateConfigurations();
}

Core Classes #

FlavorConfig: Represents a complete flavor configuration
ProvisioningConfig: Provisioning file configuration
ConfigParser: Configuration parsing and validation
FlavorOrchestrator: Main orchestration logic

See the API documentation for detailed class and method documentation.

🔒 Safety Features #

Automatic Backups #

The orchestrator automatically creates backups of all modified files before making changes. If an error occurs, all changes are automatically rolled back.

Validation #

All configurations are validated before being applied:

✅ Required fields presence
✅ Bundle ID format validation
✅ File existence checks
✅ YAML syntax validation

Error Handling #

Comprehensive error handling with clear, actionable error messages:

🔴 Missing configuration files
🔴 Invalid bundle ID formats
🔴 Missing native directories
🔴 File operation failures

🧪 Testing #

The package includes a comprehensive test suite:

# Run all tests
dart test

# Run with coverage
dart test --coverage

🤝 Contributing #

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments #

Built with ❤️ by Alessio La Mantia
Inspired by the need for better flavor management in Flutter projects
Uses excellent packages: args, yaml, xml, path

📞 Support #

📧 Report issues on GitHub Issues
💬 Ask questions on Stack Overflow
📖 Read the documentation

🗺️ Roadmap #

❌ Support for additional platforms (macOS, Windows, Linux)
❌ Icon generation integration
❌ Enhanced scheme management for iOS
❌ Build flavor integration with flutter build commands
❌ Interactive CLI mode
❌ Configuration templates
❌ Migration tools from other flavor solutions

Made with ❤️ for the Flutter community

flutter_flavor_orchestrator 0.1.4 flutter_flavor_orchestrator: ^0.1.4 copied to clipboard

Metadata