Engineering10 min read
Flutter App Flavors: Dev, Staging, Prod
Set up Flutter app flavors for dev, staging and production: Android product flavors, iOS schemes, dart-define config and Firebase projects in one codebase.
- #flutter
- #app-flavors
- #devops
- #firebase
- #android
- #ios

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:
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:
#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:
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:
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:
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:
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:
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.
Frequently asked questions
- What are Flutter app flavors?
- Flutter app flavors are named build variants of a single project, where each flavor produces a separate installable app with its own bundle ID, app name, icon and configuration. A typical setup has dev, staging and prod flavors sharing the same Dart code.
- How do I run a Flutter app with a flavor?
- Run flutter run --flavor dev -t lib/main.dart --dart-define=FLAVOR=dev. The --flavor flag selects the native variant and --dart-define tells Dart which flavor is running, so always pass both flags together.
- How do I give each flavor its own Firebase project?
- Run flutterfire configure once per flavor with a different project and output file, then initialize Firebase in main() with the options file that matches the active flavor. Each flavor also needs its own google-services.json on Android and GoogleService-Info.plist on iOS.
- Why is my dev build talking to the production API?
- The usual cause is running with --flavor dev but forgetting --dart-define=FLAVOR=dev, so Dart falls back to its default value while the native app is the dev variant. Put both flags in your launch configuration or CI script so they can never disagree.


