GitLocker: The Coding Marketplace

Description:

flutter flavorizr

Flutter Flavorizr #
A flutter utility to easily create flavors in your flutter application

If you want to support this project, please leave a star, share this project, or consider donating through Github Sponsor.
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.
If your app uses a Flutter plugin and you plan to create flavors for iOS and macOS, you need to make
sure there's an existing Podfile file under the ios/macos folder. This might lead to problems like
"Unable to load contents of file list".
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.3
copied to clipboard
You can install packages from the command line:
pub get
copied to clipboard
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"
copied to clipboard
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"
copied to clipboard
Available fields #
flavorizr

key
type
default
required
description

app
Object

false
An object describing the general capabilities of an app

flavors
Array

true
An array of items. Each of them describes a flavor configuration

instructions
Array

false
An array of instructions to customize the flavorizr process

assetsUrl
String
link
false
A string containing the URL of the zip assets file. The default points to the current release

ide
String

false
The IDE in which the app is being developed. Currently only vscode or idea

Available instructions

value
category
description

assets:download
Miscellaneous
Downloads the assets zip from the network

assets:extract
Miscellaneous
Extracts the downloaded zip in the project .tmp directory

assets:clean
Miscellaneous
Removes the assets from the project directory

android:buildGradle
Android
Adds the flavors to the Android build.gradle file

android:androidManifest
Android
Changes the reference of the app name in the AndroidManifest.xml

android:dummyAssets
Android
Generates some default icons for your custom flavors

android:icons
Android
Creates a set of icons for each flavor according to the icon directive

flutter:flavors
Flutter
Creates the flutter flavor configuration file

flutter:app
Flutter
Creates the app.dart entry

flutter:pages
Flutter
Creates a set of default pages for the app

flutter:main
Flutter
Creates the main target to run the app

flutter:targets
Flutter
Creates a set of targets for each flavor instance

google:firebase
Google
Adds Google Firebase configurations for Android and iOS for each flavor

huawei:agconnect
Huawei
Adds Huawei AGConnect configurations for Android for each flavor

ide:config
IDE
Generates debugging configurations for each flavor of your IDE

ios:podfile
iOS
Updates the Pods-Runner path for each flavor

ios:xcconfig
iOS
Creates a set of xcconfig files for each flavor and build configuration

ios:buildTargets
iOS
Creates a set of build targets for each flavor and build configuration

ios:schema
iOS
Creates a set of schemas for each flavor

ios:dummyAssets
iOS
Generates some default icons for your custom flavors

ios:icons
iOS
Creates a set of icons for each flavor according to the icon directive

ios:plist
iOS
Updates the info.plist file

ios:launchScreen
iOS
Creates a set of launchscreens for each flavor

macos:podfile
macOS
Updates the Pods-Runner path for each flavor

macos:xcconfig
macOS
Creates a set of xcconfig files for each flavor and build configuration

macos:configs
macOS
Creates a set of xcconfig files for each flavor and build configuration

macos:buildTargets
macOS
Creates a set of build targets for each flavor and build configuration

macos:schema
macOS
Creates a set of schemas for each flavor

macos:dummyAssets
macOS
Generates some default icons for your custom flavors

macos:icons
macOS
Creates a set of icons for each flavor according to the icon directive

macos:plist
macOS
Updates the info.plist file

android (under app)

key
type
default
required
description

flavorDimensions
String
"flavor-type"
false
The value of the flavorDimensions in the android build.gradle file

resValues
Array
{}
false
An array which contains a set of resValues configurations

buildConfigFields
Array
{}
false
An array which contains a set of buildConfigFields configurations

ios (under app)

key
type
default
required
description

buildSettings
Dictionary
{}
false
An XCode build configuration dictionary XCode Build Settings

macos (under app)

key
type
default
required
description

buildSettings
Dictionary
{}
false
An XCode build configuration dictionary XCode Build Settings

app (under flavorname)

key
type
default
required
description

name
String

true
The name of the App

icon
String

false
The icon path for this flavor

android (under flavorname)

key
type
default
required
description

applicationId
String

true
The applicationId of the Android App

firebase
Object

false
An object which contains a Firebase configuration

resValues
Array

false
An array which contains a set of resValues configurations

buildConfigFields
Array

false
An array which contains a set of buildConfigFields configurations

customConfig
Array

false
An array which contains a set of custom configs, overrides defaultConfig

generateDummyAssets
bool
true
false
True if you want to generate dummy assets (icon set, strings, etc)

icon
String

false
The icon path for this android flavor

adaptiveIcon
Array

false
An array which contains foreground and background of adaptive icon

ios (under flavorname)

key
type
default
required
description

bundleId
String

true
The bundleId of the iOS App

buildSettings
Dictionary
{}
false
A flavor-specific XCode build configuration dictionary XCode Build Settings

firebase
Object

false
An object which contains a Firebase configuration

variables
Array

false
An array which contains a set of variables configurations

generateDummyAssets
bool
true
false
True if you want to generate dummy assets (xcassets, etc)

icon
String

false
The icon path for this iOS flavor

macos (under flavorname)

key
type
default
required
description

bundleId
String

true
The bundleId of the macOS App

buildSettings
Dictionary
{}
false
A flavor-specific XCode build configuration dictionary XCode Build Settings

firebase
Object

false
An object which contains a Firebase configuration

variables
Array

false
An array which contains a set of variables configurations

generateDummyAssets
bool
true
false
True if you want to generate dummy assets (xcassets, etc)

icon
String

false
The icon path for this macOS flavor

firebase

key
type
default
required
description

config
String

false
The path to the Firebase configuration file (google-services.json for Android and GoogleService-Info.plist for iOS and macOS)

agconnect (for Android)

key
type
default
required
description

config
String

false
The path to the AGConnect configuration file (agconnect-services.json)

resValue (for Android)

key
type
default
required
description

type
String

true
The type of the resValue variable

value
String

true
The value of the resValue variable

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"
copied to clipboard
buildConfigField (for Android)

key
type
default
required
description

type
String

true
The type of the buildConfigField variable

value
String

true
The value of the buildConfigField variable

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

android:
applicationId: "com.example.apple"
buildConfigFields:
field_one:
type: "String"
value: "example field one"
field_two:
type: "char"
value: "y"
field_three:
type: "double"
value: "20.0"

ios:
bundleId: "com.example.apple"
copied to clipboard
variable (for iOS and macOS)

key
type
default
required
description

target
String

false
The type of the target (debug, release, profile). Do not specify a target if you want to apply it to all of them.

value
String

true
The value of the variable

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"
copied to clipboard
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
copied to clipboard
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
}
copied to clipboard
adaptiveIcon (for Android only)
You can define adaptiveIcon for android:
flavors:
apple:
app:
name: "Apple App"

android:
applicationId: "com.example.apple"
icon: "assets/icon/appleApp/ic_launcher.png"
adaptiveIcon:
foreground: "assets/adaptive_icon/appleApp/ic_launcher_foreground.png"
background: "assets/adaptive_icon/appleApp/ic_launcher_background.png"
copied to clipboard
After removing adaptiveIcon key, the adaptive icons generated before will still exist. Please delete adaptiveIcon manually.
Usage #
When you finished defining the flavorizr configuration, you can proceed by running the script with:
flutter pub run flutter_flavorizr
copied to clipboard
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>
copied to clipboard
Example
flutter pub run flutter_flavorizr -p assets:download
flutter pub run flutter_flavorizr -p assets:download,assets:extract
copied to clipboard
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
copied to clipboard
Example
flutter run --flavor apple -t lib/main_apple.dart
flutter run --flavor banana -t lib/main_banana.dart
copied to clipboard
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:podfile
ios:xcconfig
ios:buildTargets
ios:schema
ios:dummyAssets
ios:icons
ios:plist
ios:launchScreen
macos:podfile
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';
}
}

}
copied to clipboard
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"
copied to clipboard
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"
copied to clipboard
Troubleshooting #
How to fix the error "Unable to load contents of file list"
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.