Flutter Flavors: One Codebase, Multiple App Versions

Why it exists

Managing different application environments—like development, staging, and production—without a formal system is error-prone. Developers often resort to manually changing API URLs in the code, leading to messy commits and the high risk of accidentally testing against live production data or deploying with the wrong settings.

The mental model

Think of Flutter Flavors like a restaurant kitchen that uses the same core ingredients to create multiple different dishes. Your codebase is the set of ingredients, and each flavor (dev, staging, prod) is a distinct dish with its own specific configuration, like a different app name, API endpoint, or color scheme.

How it works

Flavors work by defining separate build configurations at the native level (Android and iOS) and linking them to your Dart code. You select a flavor at build time using a command-line flag, like flutter run --flavor dev. This command tells the build tools to use a specific configuration. For Android, this is done in the build.gradle file by defining productFlavors. For iOS, it involves creating new build schemes in Xcode. Your Dart code can then access flavor-specific values using String.fromEnvironment to read variables passed in during the build.

When to use it

Use flavors when you need to maintain multiple versions of your app from a single codebase. This is essential for isolating development, staging, and production environments to prevent bugs and data corruption. It's also ideal for creating white-label apps, where you build customized versions for different clients by changing branding and features without forking the project.

When not to use it

For a very simple application with no distinct development or staging environments, flavors might be overkill. If your app has only one target deployment and you don't need to manage different API keys or configurations, the initial setup for flavors might add unnecessary complexity.

One canonical example

A standard setup involves creating dev, staging, and prod flavors. In the Android configuration file android/app/build.gradle, you would define these inside the productFlavors block. The dev flavor might get an applicationIdSuffix of ".dev" and an app name of "MyApp Dev". The staging flavor would get ".staging" and "MyApp Staging". The prod flavor would have no suffix, representing the final release version. This ensures each flavor can be installed on a device simultaneously without conflicts.