Flutter Flavorizr

A flutter utility to easily create flavors in your flutter application

If you want to support this project,

Getting Started

Let's start by setting up our environment in order to run Flutter Flavorizr

Prerequisites

Side note: this tool works better on a new and clean Flutter project. Since some processors reference some existing files and a specific base structure, it could be possible that running Flutter Flavorizr over an existing project could throw errors.

Before running Flutter Flavorizr, you must install the following software:

• Ruby
• Gem
• Xcodeproj (through RubyGems)

These prerequisites are needed to manipulate the iOS and macOS projects and schemes. If you are interested in flavorizing Android only, you can skip this step. Keep in mind that you will have to use a custom instructions set with Android and Flutter processors only, otherwise an error will occur.

Installation

This package is intended to support development of Flutter projects. In general, put it under dev_dependencies, in your pubspec.yaml:

dev_dependencies:
  flutter_flavorizr: ^2.2.1

You can install packages from the command line:

pub get

Create your flavors

Once all of the prerequisites have been installed and you have added flutter_flavorizr as a dev dependency, you have to edit your pubspec.yaml and define the flavors.

Example

Create a new file named flavorizr.yaml and define the name of the flavors, in our example apple and banana. For each flavor you have to specify the app name, the applicationId and the bundleId.

flavors:
  apple:
    app:
      name: "Apple App"

    android:
      applicationId: "com.example.apple"  
    ios:
      bundleId: "com.example.apple"
    macos:
      bundleId: "com.example.apple"  
  banana:
    app:
      name: "Banana App"
  
    android:
      applicationId: "com.example.banana"
    ios:
      bundleId: "com.example.banana"
    macos:
      bundleId: "com.example.banana"

Alternatively, add a new key named flavorizr and define a sub item named flavors. Under the flavors array you can define the name of the flavors, in our example apple and banana. For each flavor you have to specify the app name, the applicationId and the bundleId. This way of defining flavors will be deprecated in versions 3.x

flavorizr:
  flavors:
    apple:
      app:
        name: "Apple App"

      android:
        applicationId: "com.example.apple"
      ios:
        bundleId: "com.example.apple"
      macos:
        bundleId: "com.example.apple"        
    banana:
      app:
        name: "Banana App"

      android:
        applicationId: "com.example.banana"
      ios:
        bundleId: "com.example.banana"
      macos:
        bundleId: "com.example.banana"

Available fields

flavorizr

Available instructions

android (under app)

ios (under app)

macos (under app)

app (under flavorname)

android (under flavorname)

ios (under flavorname)

macos (under flavorname)

firebase

agconnect (for Android)

resValue (for Android)

flavors:
  apple:
    app:
      name: "Apple App"
  
    android:
      applicationId: "com.example.apple"
      resValues:
        variable_one:
          type: "string"
          value: "example variable one"
        variable_two:
          type: "string"
          value: "example variable two"
  
    ios:
      bundleId: "com.example.apple"

variable (for iOS and macOS)

flavors:
  apple:
    app:
      name: "Apple App"
  
    android:
      applicationId: "com.example.apple"
  
    ios:
      bundleId: "com.example.apple"
      variables:
        VARIABLE_ONE:
          value: "variable1"
        VARIABLE_TWO:
          target: "Debug"
          value: "variable2"        

customConfig (for Android only)

You can define any custom property for android

flavors:
  apple:
    app:
      name: "Apple App"
  
    android:
      applicationId: "com.example.apple"
      customConfig:
          versionNameSuffix: "\"-green-prod\"" # Don't forget to escape strings with \"
          signingConfig: flavorSigning.green
          versionCode: 1000
          minSdkVersion: 23
          # ..... and any custom property you want to add

This .yml part, generate this custom android flavor:

apple {
  dimension "flavor-type"
  applicationId "com.example.apple"
  versionNameSuffix "-green-prod"
  signingConfig flavorSigning.green
  versionCode 1000
  minSdkVersion 23
}

Usage

When you finished defining the flavorizr configuration, you can proceed by running the script with:

flutter pub run flutter_flavorizr

You can also run flutter_flavorizr with a custom set of processors by appending the -p (or --processors) param followed by the processor names separated by comma:

flutter pub run flutter_flavorizr -p <processor_1>,<processor_2>

Example

flutter pub run flutter_flavorizr -p assets:download
flutter pub run flutter_flavorizr -p assets:download,assets:extract

Run your flavors

Once the process has generated the flavors, you can run them by typing

flutter run --flavor <flavorName> -t lib/main_<flavorName>.dart

Example

flutter run --flavor apple -t lib/main_apple.dart
flutter run --flavor banana -t lib/main_banana.dart

Currently, due to a bug in the Flutter SDK, it's not possible to run the macOS flavors from the terminal. You can run them from XCode by selecting the proper schema and by pressing play.

Default processors set

By default, when you do not specify a custom set of processors by appending the -p (or --processors) param, a default processors set will be used:

• assets:download
• assets:extract
• android:androidManifest
• android:buildGradle
• android:dummyAssets
• android:icons
• flutter:flavors
• flutter:app
• flutter:pages
• flutter:main
• flutter:targets
• ios:xcconfig
• ios:buildTargets
• ios:schema
• ios:dummyAssets
• ios:icons
• ios:plist
• ios:launchScreen
• macos:xcconfig
• macos:configs
• macos:buildTargets
• macos:schema
• macos:dummyAssets
• macos:icons
• macos:plist
• google:firebase
• huawei:agconnect
• assets:clean
• ide:config

Customize your app

Flutter_flavorizr creates different dart files in the lib folder. In the flavors.dart file we have the F class which contains all of our customizations.

class F {
  static Flavor? appFlavor;

  static String get title {
    switch (appFlavor) {
      case Flavor.APPLE:
        return 'Apple App';
      case Flavor.BANANA:
        return 'Banana App';
      default:
        return 'title';
    }
  }

}

The process creates a simple title customization: a switch which checks the current appFlavor (defined in our app starting point) and returns the correct value. Here you can write whatever you want, you can create your custom app color palette, differentiate the URL action of a button, and so on.

If you are wondering how to use these getters, you can find an example under the pages folder: in the my_home_page.dart file, the page shown after the launch of the app, we can see a clear reference on the title getter defined in the F class.

Side notes

I haven't found yet a good groovy parser to guarantee the idempotency of the AndroidBuildGradleProcessor.
The only way to keep track of the autogenerated flavorDimensions is to mark up the beginning and the end of the section with magic comments.
Please do not erase these comments otherwise you will break down the AndroidBuildGradleProcessor.

Third party services

Google Firebase

In order to flavorize your project and enable Firebase in your flavor you have to define a firebase object below each OS flavor. Under the firebase object you must define the config path of the google-services.json (if you are under Android configuration) or GoogleService-Info.plist (if you are under iOS or macOS configuration).

As you can see in the example below, we added the path accordingly

flavors:
  apple:
    app:
      name: "Apple App"
  
    android:
      applicationId: "com.example.apple"
      firebase:
        config: ".firebase/apple/google-services.json"
  
    ios:
      bundleId: "com.example.apple"
      firebase:
        config: ".firebase/apple/GoogleService-Info.plist"
  
  banana:
    app:
      name: "Banana App"
      
    android:
      applicationId: "com.example.banana"
      firebase:
        config: ".firebase/banana/google-services.json"
    ios:
      bundleId: "com.example.banana"
      firebase:
        config: ".firebase/banana/GoogleService-Info.plist"

Huawei AppGallery Connect

In order to flavorize your project and enable AppGallery Connect in your flavor
you have to define an agconnect object below each Android flavor. Under the agconnect object you must define the config path of the agconnect-services.json.

As you can see in the example below, we added the path accordingly

flavors:
  apple:
    app:
      name: "Apple App"
  
    android:
      applicationId: "com.example.apple"
      agconnect:
        config: ".agconnect/apple/agconnect-services.json"
  
    ios:
      bundleId: "com.example.apple"
  
  banana:
    app:
      name: "Banana App"
      
    android:
      applicationId: "com.example.banana"
      agconnect:
        config: ".agconnect/banana/agconnect-services.json"
    ios:
      bundleId: "com.example.banana"

Docs & Tutorials (from the community)

Easily build flavors in Flutter (Android and iOS) with flutter_flavorizr - Angelo Cassano

Get the best out of Flutter flavors with flutter_flavorizr - Pierre Monier

Further developments

• Let the user define its custom set of available instructions.

Questions and bugs

Please feel free to submit new issues if you encounter problems while using this library.

If you need help with the use of the library or you just want to request new features, please use the Discussions section of the repository. Issues opened as questions will be automatically closed.

License

Flutter Flavorizr is available under the MIT license. See the LICENSE file for more info.