Contents

Creating flavors for Flutter

Contents

What are flavors

Have you ever wondered how to set up different environments in your Flutter app? Flavors (known as build configurations in iOS), allow you (the developer) to create separate environments for your app using the same code base. For example, you might have one flavor for your full-fledged production app, another as a limited “free” app, another for testing experimental features, and so on.

Say you want to make both free and paid versions of your Flutter app. You can use flavors to set up both app versions without writing two separate apps. For example, the free version of the app has basic functionality and ads. In contrast, the paid version has basic app functionality, extra features, different styles for paid users, and no ads.

You also might use flavors for feature development. If you’ve built a new feature and want to try it out, you could set up a flavor to test it out. Your production code remains unaffected until you’re ready to deploy your new feature.

Flavors let you define compile-time configurations and set parameters that are read at runtime to customize your app’s behavior.

This document guides you through setting up Flutter flavors for iOS and Android.

Environment set up

Prerequisites:

  • Xcode installed
  • An existing Flutter project

To set up flavors in iOS, you’ll define build configurations in Xcode.

Creating flavors in iOS

  1. Open your project in Xcode.

  2. Select Runner > New Scheme from the menu to add a new Scheme.

    • A scheme describes how Xcode runs different actions. For the purposes of this guide, the example flavor and scheme are named free. The build configurations in the free scheme have the -free suffix.

  3. Duplicate the build configurations to differentiate between the default configurations that are already available and the new configurations for the free scheme.

    • Under the Info tab at the end of the Configurations dropdown list, click the plus button and duplicate each configuration name (Debug, Release, and Profile). Duplicate the existing configurations, once for each environment.

    Step 3 Xcode image

  4. To match the free flavor, add -free at the end of each new configuration name.

  5. Change the free scheme to match the build configurations already created.

    • In the Runner project, click Manage Schemes… and a pop up window opens.
    • Double click the free scheme. In the next step (as shown in the screenshot), you’ll modify each scheme to match its free build configuration:

    Step 5 Xcode image

Using flavors in iOS

Now that you’ve set up your free flavor, you can, for example, add different product bundle identifiers per flavor. A bundle identifier uniquely identifies your application. In this example, we set the Debug-free value to equal com.flavor-test.free.

  1. Change the app bundle identifier to differentiate between schemes. In Product Bundle Identifier, append .free to each -free scheme value.

    Step 1 using flavors image.

  2. In the Build Settings, set the Product Name value to match each flavor. For example, add Debug Free.

    Step 2 using flavors image.

  3. Add the display name to Info.plist. Update the Bundle Display Name value to $(PRODUCT_NAME).

    Step 3 using flavors image.

Now you have set up your flavor by making a free scheme in Xcode and setting the build configurations for that scheme.

For more information, skip to the Launching your app flavors section at the end of this document.

Plugin configurations

If your app uses a Flutter plugin, you need to update the ios/Podfile.

  1. In ios/Podfile change the default for Debug, Profile, and Release to match the Xcode build configurations for the free scheme.
project 'Runner', {
  'Debug-free' => :debug,
  'Profile-free' => :release,
  'Release-free' => :release,
}

Using flavors in Android

Setting up flavors in Android can be done in your project’s build.gradle file.

  1. Inside your Flutter project, navigate to android/app/build.gradle.

  2. Create a flavorDimension to group your added product flavors. Gradle doesn’t combine product flavors that share the same dimension.

  3. Add a productFlavors object with the desired flavors along with values for dimension, resValue, and applicationId or applicationSuffix.

    • The name of the application for each build is located in resValue.
    • If you specify a applicationSuffix instead of a applicationId, it is appended to the “base” application id.
flavorDimensions "default"

productFlavors {
    free {
        dimension "default"
        resValue "string", "app_name", "free flavor example"
        applicationSuffix ".free"
    }
}

Setting up launch configurations

Next, add a launch.json file; this allows you to run the command flutter run --flavor [environment name].

In VSCode, set up the launch configurations as follows:

  1. In the root directory of your project, add a folder called .vscode.
  2. Inside the .vscode folder, create a file named launch.json.
  3. In the launch.json file, add a configuration object for each flavor. Each configuration has a name, request, type, program, and args key.
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "free",
      "request": "launch",
      "type": "dart",
      "program": "lib/main_development.dart",
      "args": ["--flavor", "free", "--target", "lib/main_free.dart" ]
    }
  ],
  "compounds": []
}

You can now run the terminal command flutter run --flavor free or you can set up a run configuration in your IDE.

Launching your app flavors

  1. Once the flavors are set up, modify the Dart code in lib / main.dart to consume the flavors.
  2. Test the setup using flutter run --flavor free at the command line, or in your IDE.

For examples of build flavors for iOS (Xcode) and Android, check out the integration test samples in the Flutter repo.

More information

For more information on creating and using flavors, check out the following resources:

Packages

For packages that support creating flavors, check out the following: