DOCSEARCHbyAlgolia
Submit Docs

flutter_flavorizr

repository·master·Indexed 20 days ago

https://github.com/angeloavv/flutter_flavorizr

A utility for simplifying the creation and management of flavors in Flutter applications. It automates the configuration of platform-specific identifiers (applicationId, bundleId), app icons, launch screens, and native build settings for Android, iOS, macOS, Linux, and Windows. The tool supports custom processors, global settings via flavorizr.yaml, and integration with Google Firebase and Huawei AppGallery Connect.

Tokens
4.9K
Snippets
20
Records
23
Agent score
68%

What's inside flutter_flavorizr

  1. Use custom processors with specific ordering

    master

    You can run flutter_flavorizr with a custom set of processors using the -p or --processors flag.

    Important: The order of processors is critical. Some processors depend on others. As a rule of thumb, you should always run assets:download and assets:extract before any other processor. For example, android:dummyAssets requires assets:download to have run first.

    # Example: downloading and then extracting assets
flutter pub run flutter_flavorizr -p assets:download,assets:extract

  3. Install flutter_flavorizr

    master

    To use flutter_flavorizr, add it to your dev_dependencies in your pubspec.yaml file. It is recommended to use it in new, clean Flutter projects to avoid errors caused by existing file structures that the tool's processors might reference.

    dev_dependencies:
  flutter_flavorizr: ^2.6.0

  4. Run the flutter_flavorizr script

    master

    Once you have defined your configuration, execute the flavorization process using the following command. You can also customize which processors run, enable verbose logging, or skip confirmation prompts.

    # Run with default processors
flutter pub run flutter_flavorizr

# Run with a custom set of processors (order matters)
flutter pub run flutter_flavorizr -p <processor_1>,<processor_2>

# Run in verbose mode to see all logs
flutter pub run flutter_flavorizr -v

# Run and skip the confirmation step
flutter pub run flutter_flavorizr -f

  5. Customize iOS launch screen assets

    master

    To customize the launch screen for your iOS flavor, you can either replace the image files directly in the generated directory or use Xcode.

    Option 1: Direct File Replacement Replace the existing image files within the example/ios/Runner/Assets.xcassets/bananaLaunchImage.imageset/ directory with your own assets.

    Option 2: Using Xcode

    1. Open your iOS project in Xcode using the command: open ios/Runner.xcworkspace.
    2. In the Project Navigator, navigate to Runner/Assets.xcassets.
    3. Drag and drop your desired images into the asset catalog.
    open ios/Runner.xcworkspace

  7. Define flavors using flavorizr.yaml or pubspec.yaml

    master

    To configure flavors, you can either create a standalone flavorizr.yaml file (recommended) or add a flavorizr key directly to your pubspec.yaml.

    Note: Defining flavors under the flavorizr key in pubspec.yaml is deprecated and will be removed in version 3.x. Use a separate flavorizr.yaml file instead.

    For each flavor, you must specify the app name, and platform-specific identifiers like applicationId (Android/Linux) or bundleId (iOS/macOS).

    # Recommended: flavorizr.yaml
flavors:
  apple:
    app:
      name: "Apple App"
    android:
      applicationId: "com.example.apple"
    ios:
      bundleId: "com.example.apple"
    macos:
      bundleId: "com.example.apple"
    linux:
      applicationId: "com.example.apple"
    windows: {}
  banana:
    app:
      name: "Banana App"
    android:
      applicationId: "com.example.banana"
    ios:
      bundleId: "com.example.banana"
    macos:
      bundleId: "com.example.banana"
    linux:
      applicationId: "com.example.banana"
    windows: {}

  8. Configure flavorizr global settings

    master

    The top-level flavorizr object allows you to configure global settings that apply to the entire flavorization process.

    keytypedefaultrequireddescription
    appObjectfalseAn object describing general app capabilities
    flavorsArraytrueAn array of flavor configurations
    instructionsArrayfalseAn array of instructions to customize the process
    assetsUrlStringlinkfalseURL of the zip assets file
    ideArrayfalseThe IDE being used (vscode or idea)

  9. Configure Android-specific flavor settings

    master

    Under each flavor, you can define an android block to customize Android-specific properties.

    Key Fields:

    • applicationId: The unique ID for the Android app (Required).
    • resValues: An array of resValue objects (type and value).
    • buildConfigFields: An array of buildConfigField objects (type and value).
    • customConfig: An object containing any custom property you want to add to the generated Gradle flavor block (e.g., versionCode, minSdkVersion).
    • icon: Path to the flavor's icon.
    • adaptiveIcon: Configuration for Android adaptive icons including foreground, background, and optional monochrome.
    • generateDummyAssets: Boolean to toggle dummy asset generation (defaults to true).
    • firebase: Object containing the path to the Firebase configuration file via config.
    flavors:
  apple:
    android:
      applicationId: "com.example.apple"
      resValues:
        variable_one:
          type: "string"
          value: "example variable one"
      buildConfigFields:
        field_one:
          type: "String"
          value: "example field one"
      customConfig:
        versionCode: 1000
        minSdkVersion: 23
      adaptiveIcon:
        foreground: "assets/adaptive_icon/appleApp/ic_launcher_foreground.png"
        background: "assets/adaptive_icon/appleApp/ic_launcher_background.png"

  10. Configure iOS and macOS-specific flavor settings

    master

    Under each flavor, you can define ios or macos blocks.

    Key Fields:

    • bundleId: The unique ID for the app (Required).
    • buildSettings: A dictionary of XCode build configuration settings.
    • variables: An array of variables to be injected into the build. Each variable can have a value and an optional target (debug, release, profile).
    • includes: A list of .xcconfig files to include. Each entry can have a value (path), an optional target, and an optional boolean (if true, uses #include? so the build won't fail if the file is missing).
    • firebase: Object containing the path to the Firebase configuration file via config.
    • icon: Path to the flavor's icon.
    • generateDummyAssets: Boolean to toggle dummy asset generation (defaults to true).
    flavors:
  apple:
    ios:
      bundleId: "com.example.apple"
      variables:
        VARIABLE_ONE:
          value: "variable1"
        VARIABLE_TWO:
          target: "Debug"
          value: "variable2"
      includes:
        - value: "Apple/flavor.xcconfig"
        - value: "Apple/optional.xcconfig"
          optional: true

  11. Configure Huawei AppGallery Connect for flavors

    master

    To enable AppGallery Connect in specific Android flavors, define an agconnect object under the Android configuration in your flavorizr config. You must provide the path to the agconnect-services.json file.

    flavors:
  apple:
    android:
      agconnect:
        config: ".agconnect/apple/agconnect-services.json"

  12. Configure Google Firebase for flavors

    master

    To enable Firebase in specific flavors, define a firebase object under the corresponding OS configuration in your flavorizr config. You must provide the path to the google-services.json (Android) or GoogleService-Info.plist (iOS/macOS) file.

    Note: After running flutter_flavorizr, you must manually add the native dependencies. When initializing Firebase in your Dart code, do not pass FirebaseOptions; let the native configuration handle it.

    flavors:
  apple:
    android:
      firebase:
        config: ".firebase/apple/google-services.json"
    ios:
      firebase:
        config: ".firebase/apple/GoogleService-Info.plist"
    // Correct initialization in main.dart
Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(); // Do not pass options here
  runApp(const App());
}