Skip to content
Tutorials Center
My learning

Topics

Lesson 60 of 73 ยท Publishing

Build Flavors, Environments and Config

Run one Flutter codebase as dev, staging and production apps: dart-define, Android and iOS flavors, app icons, splash screens and version numbers.

Sooner or later one build of your app is not enough. You want a dev app that talks to a test server, a staging app for testers, and the production app that customers install. You want all three on the same phone at the same time, with different names and icons so nobody mixes them up. And every build needs a version number the stores will accept.

Flutter gives you two tools for this. Compile-time defines (--dart-define) inject values into Dart code. Flavors are a native feature of Android and iOS that change the app id, name, icon and signing per environment. This lesson shows both, plus icons, splash screens and versioning. Publishing itself comes next in Publishing to Google Play and the App Store.

Real vs stand-in. Every Dart, Gradle, Xcode and shell snippet is real and read-only here, because the site has no Flutter toolchain. The live examples are JavaScript stand-ins that mimic how defines are parsed and how version numbers are compared.

One codebase, many apps

Dev Test server, debug tools.
Staging Close to production, for testers.
Production The app customers install.
1 / 2

Compile-time values with dart-define

The simplest way to change behavior per environment is to pass values when you build. They are baked into the app as constants:

Terminal
flutter run --dart-define=API_URL=https://api.dev.example.com --dart-define=ENABLE_LOGS=true

In Dart you read them with String.fromEnvironment, bool.fromEnvironment and int.fromEnvironment:

DART
class Env {
  static const apiUrl = String.fromEnvironment(
    'API_URL',
    defaultValue: 'https://api.example.com',
  );
  static const enableLogs = bool.fromEnvironment('ENABLE_LOGS');
  static const timeoutSeconds = int.fromEnvironment('TIMEOUT', defaultValue: 10);
}

These must be declared const. The lookup happens at compile time, which means the compiler can remove code behind if (Env.enableLogs) when the flag is false.

Long command lines get tiring, so put the values in a JSON file and pass it once:

JSON
{
  "API_URL": "https://api.staging.example.com",
  "ENABLE_LOGS": "true"
}
Terminal
flutter run --dart-define-from-file=config/staging.json
flutter build apk --dart-define-from-file=config/prod.json

Defines are not secrets. Anything compiled into the app can be extracted by someone with the APK or IPA. Use defines for URLs and feature switches, never for private API keys or passwords. See Security in Flutter Apps.

A stand-in for define parsing

This example parses --dart-define style arguments into a map and reads them with defaults and types, like the three fromEnvironment constructors do.

JS Parsing --dart-define arguments

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Flavors: different apps from one code

Defines change Dart values only. They cannot give the app another package name, icon or display name. For that you need flavors.

Android

In android/app/build.gradle.kts declare a flavor dimension and product flavors:

Kotlin
android {
    flavorDimensions += "env"
    productFlavors {
        create("dev") {
            dimension = "env"
            applicationIdSuffix = ".dev"
            resValue("string", "app_name", "Shop Dev")
        }
        create("staging") {
            dimension = "env"
            applicationIdSuffix = ".staging"
            resValue("string", "app_name", "Shop Staging")
        }
        create("prod") {
            dimension = "env"
            resValue("string", "app_name", "Shop")
        }
    }
}

In AndroidManifest.xml set android:label="@string/app_name". Because the application ids differ (com.example.shop.dev and so on), Android treats the apps as separate and installs them side by side.

iOS

iOS has no "flavor" word. You create build configurations and schemes in Xcode: duplicate Debug, Release and Profile as Debug-dev, Release-dev and so on, then make one scheme per flavor named exactly like the flavor. Per configuration you set the product bundle identifier and the display name in build settings. Flutter looks for a scheme with the flavor name.

Running a flavor

Terminal
flutter run --flavor dev -t lib/main_dev.dart
flutter build appbundle --flavor prod -t lib/main_prod.dart --dart-define-from-file=config/prod.json

The -t (target) flag picks the entry point. A common pattern is a tiny main_dev.dart per environment that builds a config object and calls a shared runApp:

DART
// lib/main_dev.dart
import 'bootstrap.dart';

void main() => bootstrap(const AppConfig(
      name: 'Dev',
      apiUrl: 'https://api.dev.example.com',
    ));

You can combine both mechanisms: the flavor decides the native identity, while --dart-define-from-file supplies the values. Inside Dart you can even read the flavor name through appFlavor from package:flutter/services.dart, which is set when you pass --flavor.

App icons and splash screens

Different flavors should look different on the home screen. Two popular packages generate the platform files from one source image:

YAML
# pubspec.yaml
dev_dependencies:
  flutter_launcher_icons: ^0.14.0
  flutter_native_splash: ^2.4.0
YAML
# flutter_launcher_icons-dev.yaml
flutter_launcher_icons:
  android: true
  ios: true
  image_path: assets/icons/icon_dev.png
  adaptive_icon_background: "#1B5E20"
  adaptive_icon_foreground: assets/icons/icon_foreground.png
Terminal
dart run flutter_launcher_icons -f flutter_launcher_icons-dev.yaml
dart run flutter_native_splash:create

The tools write real files into android/ and ios/. Check the version numbers in pub.dev before copying them, since packages move on.

A native splash screen is what the OS shows while the Flutter engine starts. It is only a color and a logo; it cannot run Dart code. Keep it plain and match your first screen's background so the handover is smooth. Android 12 and later always use their own splash system (icon on a background color), so design for that.

Version numbers

Your version lives in one line of pubspec.yaml:

YAML
version: 1.4.2+17

The part before + is the build name that users see (1.4.2). The part after is the build number (17): on Android it becomes versionCode, on iOS CFBundleVersion. The stores demand that the build number grows with every upload, so Google Play rejects a second upload with 17, and App Store Connect rejects a duplicate for the same version. You can override both in CI:

Terminal
flutter build ipa --build-name=1.4.2 --build-number=$GITHUB_RUN_NUMBER

A stand-in for version rules

JS Compare and bump versions

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which flag gives the Dart code a value such as API_URL at build time?

    --dart-define=KEY=VALUE is read in Dart with String.fromEnvironment, bool.fromEnvironment or int.fromEnvironment.
  2. 2. Why can a dev and a prod build be installed on one phone?

    A flavor can add a suffix such as .dev to the application id, so the OS sees two separate apps.
  3. 3. Is --dart-define a safe place for a private API secret?

    Defines are compiled into the binary. Treat them as public configuration.
  4. 4. In version: 2.0.1+30, what is 30?

    The part after + becomes versionCode on Android and CFBundleVersion on iOS.

Summary

  • --dart-define and --dart-define-from-file pass compile-time constants; read them with fromEnvironment and never store secrets there.
  • Flavors change native identity: application id, name, icon and signing, per environment.
  • On Android use productFlavors; on iOS use build configurations and schemes; run with --flavor and -t.
  • Generate icons and splash screens from one source image with packages; the splash is native and cannot run Dart.
  • version: name+build lives in pubspec.yaml; the build number must grow with every upload.

Next: Publishing to Google Play and the App Store