Shipping a Flutter app usually means juggling three versions of the same code: a dev build that talks to a test backend, a staging build for QA, and the production build your users install. The naive approach is to keep three copies of the project or to hardcode a different API URL before every release. Both break sooner or later, usually the night before a deadline.
Flutter flavors solve this properly. A flavor is a build variant of the same codebase: one project, one set of screens, and a different app name, bundle ID, icon, and backend for each environment.
What are Flutter app flavors?
Flutter app flavors are named build variants of a single Flutter project, where each flavor produces a separate installable app with its own bundle ID, app name, icon, and configuration. A typical setup has three flavors: dev for daily development against a test backend, staging for QA against a production-like backend, and prod for the release build your users install. All three flavors share the same Dart code, but each one can point at a different API base URL, a different Firebase project, and a different set of feature flags.
Flavors are not a Flutter invention. They are the standard build-variant mechanism of the native platforms: Android calls them product flavors and iOS implements them with schemes and build configurations. Flutter adds a --flavor\ flag to flutter run\ and flutter build\ that selects which native variant to build, and a --dart-define\ flag that passes the flavor name into Dart code at compile time.
Why use flavors instead of three separate apps?
Three separate copies of a project is the most common way teams start, and it is also the fastest way to drift. A bug fixed in the dev copy does not exist in the prod copy until someone remembers to copy it, and a hotfix applied to prod never reaches dev. Flavors remove that entire class of mistake, because there is only one codebase and the environment is a build-time choice, not a code change.
| Approach | Codebases | Risk of drift | Install side by side |
|---|---|---|---|
| Three project copies | 3 | High, fixes must be copied | Yes |
| One project, hardcoded URLs | 1 | High, a release can ship a test URL | No |
| Flutter flavors | 1 | Low, environment is a build flag | Yes |
Flavors also make testing honest. A staging build is the same binary shape as production, built from the same commit, so a bug that appears in staging is a bug that would appear in production. That is the whole point of staging, and it only works when QA tests the build produced the same way as the release build.
How do flavors work on Android?
On Android, flavors are Gradle product flavors declared in android/app/build.gradle.kts\. Each flavor gets a dimension, and usually an applicationIdSuffix\ so the builds install side by side, plus manifest placeholders for the app name and any other per-flavor value. A typical setup looks like this:
\`kotlin
android {
flavorDimensions += "environment"
productFlavors { create("dev") { dimension = "environment" applicationIdSuffix = ".dev" manifestPlaceholders["appName"] = "My App (Dev)" } create("staging") { dimension = "environment" applicationIdSuffix = ".staging" manifestPlaceholders["appName"] = "My App (Staging)" } create("prod") { dimension = "environment" manifestPlaceholders["appName"] = "My App" } } }
`\
With this in place, flutter run --flavor dev\ builds the devDebug\ variant and installs an app with the package name com.example.myapp.dev\, while flutter build apk --flavor prod --release\ builds the production variant with the plain package name. The app name placeholder is used in AndroidManifest.xml\ through android:label="\${appName}"\, so each flavor shows its own name on the home screen. A different app icon per flavor is the same idea: put a flavor-specific res\ folder under android/app/src/dev/res\ and Gradle merges it over the main resources.
One detail catches almost everyone the first time: the google-services.json\ file for Firebase must exist per flavor. Android expects it at android/app/src/dev/google-services.json\ for the dev flavor, android/app/src/staging/google-services.json\ for staging, and the default android/app/google-services.json\ for prod. If the file is missing for a flavor, the build fails with an error about a missing google-services.json\, and the fix is always the file location, not the Gradle setup.
How do flavors work on iOS?
On iOS, flavors are Xcode schemes paired with build configurations. Flutter creates a Runner\ target with Debug and Release configurations, and each flavor needs its own pair, for example Debug-dev and Release-dev. The usual way to create them is to duplicate the existing configurations in Xcode, name them after the flavor, and then duplicate the Runner scheme once per flavor, setting each scheme to use its matching configurations.
Each flavor also needs its own bundle identifier, so the builds can coexist on one device. The cleanest way to manage that is one .xcconfig\ file per flavor, for example ios/Flutter/Dev.xcconfig\, containing the flavor-specific values:
\`ini
include "Generated.xcconfig"
PRODUCT_BUNDLE_IDENTIFIER=com.example.myapp.dev
DISPLAY_NAME=My App (Dev)
`\
The scheme for the dev flavor then uses the Dev configuration, which reads this file. The same pattern gives each flavor its own GoogleService-Info.plist\: add one per flavor to the Runner target and select the right one at build time, or keep the plist files in flavor-specific folders and reference them from the matching configuration.
The Xcode side feels fiddly compared with Gradle, and it is where most developers give up and go back to hardcoding URLs. It is worth pushing through, because the iOS configuration only needs to be done once, and after that the flavor is just a scheme name in the run command.
How do I read the current flavor in Dart code?
The native side knows which flavor is running, but Dart code needs to be told. The standard mechanism is --dart-define\, a compile-time constant passed on the command line. Define an enum and a config object that every part of the app reads from:
\`dart
enum AppFlavor { dev, staging, prod }
class AppConfig {
const AppConfig({required this.flavor, required this.apiBaseUrl});
final AppFlavor flavor;
final String apiBaseUrl;
bool get isProd => flavor == AppFlavor.prod;
}
`\
Then resolve the flavor once, in main()\, from the define:
\`dart
void main() {
const flavorName = String.fromEnvironment('FLAVOR', defaultValue: 'dev');
final flavor = AppFlavor.values.byName(flavorName);
final config = switch (flavor) {
AppFlavor.dev => const AppConfig(
flavor: AppFlavor.dev,
apiBaseUrl: 'https://api-dev.example.com',
),
AppFlavor.staging => const AppConfig(
flavor: AppFlavor.staging,
apiBaseUrl: 'https://api-staging.example.com',
),
AppFlavor.prod => const AppConfig(
flavor: AppFlavor.prod,
apiBaseUrl: 'https://api.example.com',
),
};
runApp(MyApp(config: config));
}
`\
Run it with both flags together, because --flavor\ selects the native variant and --dart-define\ tells Dart which one it is:
\bash
flutter run --flavor dev -t lib/main.dart --dart-define=FLAVOR=dev
\\
If you run with --flavor dev\ but forget the define, the app builds and launches as the dev variant while Dart quietly falls back to the defaultValue\. That mismatch is the most common flavors bug: the icon says dev, but the app is talking to the production API. Always pass both flags, and make the define part of your launch configuration or your CI script so it cannot be forgotten.
Should I use one entry point or one per flavor?
There are two ways to structure the Dart side, and the right one depends on how different your flavors are. A single main.dart\ with --dart-define\, as shown above, is the simplest setup and the right default for most apps. The flavor is just configuration: a different API URL, a different Firebase project, maybe a different log level. One entry point keeps the startup path identical for every flavor, which means a bug in startup shows up in dev before it reaches prod.
The alternative is one entry point per flavor, such as lib/main_dev.dart\, lib/main_staging.dart\, and lib/main_prod.dart\, each calling a shared run()\ function with its own config. This fits apps where the flavors genuinely differ in behavior, for example a dev build that enables a debug drawer, a staging build that forces a test payment gateway, or a prod build that disables all logging. The cost is three startup paths to keep in sync, so only take this route when the flavors need different code, not just different values.
Either way, keep the flavor-specific values in one place. Scattering String.fromEnvironment\ calls across widgets means the flavor logic is untestable and easy to get wrong. One config object, created once in main()\ and passed down through the widget tree or a provider, is the pattern that scales.
How do I use a separate Firebase project per flavor?
A separate Firebase project per flavor is the setup that makes flavors genuinely safe: dev writes to a test Firestore database, staging writes to a staging database, and only prod touches real user data. The FlutterFire CLI supports this directly. Run flutterfire configure\ once per flavor, choosing the matching Firebase project each time, and give each run a different output file:
\bash
flutterfire configure --project=my-app-dev --out=lib/firebase_options_dev.dart
flutterfire configure --project=my-app-staging --out=lib/firebase_options_staging.dart
flutterfire configure --project=my-app-prod --out=lib/firebase_options_prod.dart
\\
Then initialize Firebase in main()\ with the options file that matches the active flavor:
\`dart
import 'firebase_options_dev.dart' as dev;
import 'firebase_options_staging.dart' as staging;
import 'firebase_options_prod.dart' as prod;
FirebaseOptions get options {
switch (flavor) {
case AppFlavor.dev:
return dev.DefaultFirebaseOptions.currentPlatform;
case AppFlavor.staging:
return staging.DefaultFirebaseOptions.currentPlatform;
case AppFlavor.prod:
return prod.DefaultFirebaseOptions.currentPlatform;
}
}
await Firebase.initializeApp(options: options);
`\
Remember the native files too: each flavor needs its own google-services.json\ on Android and its own GoogleService-Info.plist\ on iOS, in the locations described earlier. When Firebase initialization crashes at startup with an error about a missing configuration, the cause is almost always one of these native files, not the Dart code. The same separation applies to other per-environment services: a different Crashlytics project per flavor means crash reports from your own testing never pollute production crash data, and a Remote Config setup per flavor lets you test feature flags in staging before they reach users.
What goes wrong most often?
The first failure is running without a flavor at all. flutter run\ with no --flavor\ flag builds the default variant, which usually behaves like prod, so a developer testing a fix can accidentally hit the production backend. Make the flavor explicit in every run command, every launch configuration, and every CI job, and there is no default to fall back to by accident.
The second failure is a mismatch between the two flags. --flavor dev\ with --dart-define=FLAVOR=prod\ builds the dev native app with production configuration, which is exactly the wrong combination. The fix is to never type the flags by hand: define them once in your IDE launch configurations and once in CI, and copy from there. If your team uses GitHub Actions for Flutter CI, the flavor and the define belong in the same workflow step, built from the same variable, so they can never disagree.
The third failure is forgetting a flavor in one place. A new flavor needs entries in Gradle, in Xcode, in the Firebase configuration, and in the Dart config switch. Miss one and the build fails or, worse, silently falls back to a default. Keep a short checklist in the project readme and walk the whole list when you add a flavor.
The short version
Flutter flavors turn three copies of an app into one codebase with three build-time identities. Android product flavors and iOS schemes give each flavor its own bundle ID, name, and icon; --dart-define\ tells Dart which flavor is running; and a separate Firebase project per flavor keeps test data out of production. Set the flags once in your launch configurations and your CI pipeline, and the environment stops being something you have to remember before every release. For a production-ready setup, also wire up Crashlytics per flavor so crash reports from development and testing never mix with real user crashes.
Get in touch and let's talk about your project.
Originally published at uzairxdev.online