0Pricing
Flutter Mobile Development · Lesson

Build Flavors and Environment Configuration

Define dev, staging, and prod flavors with per-environment assets and Dart-define configs.

Build Flavors and Environment Configuration is a free Flutter Mobile Development lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Flutter Mobile Development learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Why Build Flavors Matter

A production Flutter app rarely talks to a single backend. You need a dev build pointing at a local or staging API, a staging build for QA, and a hardened prod build for the store.

  • Flavors are named build variants that can differ in app id, icon, name, and signing.
  • Environment config is the data each flavor injects: base URLs, feature flags, API keys.

The goal: install dev, staging, and prod side-by-side on one device, each fully isolated and impossible to confuse.

The Two Layers: Native Flavors + Dart-Define

A clean setup separates two concerns:

  • Native flavors (Android productFlavors, iOS schemes/xcconfig) control the application identity: bundle id, display name, icon.
  • Dart-define values control runtime configuration your Dart code reads: API URL, environment name, log level.

Native flavors let dev, staging, and prod coexist on the device with distinct ids like com.acme.app.dev. Dart-define keeps secrets and URLs out of source control and version-pinned at compile time.

Defining a Type-Safe Environment Enum

Start in Dart with a single source of truth for which environments exist. An enum prevents typos and enables exhaustive switch handling.

This snippet is plain Dart with no Flutter dependency, so it runs anywhere.

enum Environment { dev, staging, prod }

String labelFor(Environment env) {
  switch (env) {
    case Environment.dev:
      return 'Development';
    case Environment.staging:
      return 'Staging';
    case Environment.prod:
      return 'Production';
  }
}

void main() {
  for (final env in Environment.values) {
    print('${env.name} -> ${labelFor(env)}');
  }
}

Reading Dart-Define at Compile Time

Flutter exposes compile-time constants through String.fromEnvironment, bool.fromEnvironment, and int.fromEnvironment. You pass them with --dart-define at build time.

  • Values are baked into the binary; they are NOT read at runtime from the device.
  • Always provide a defaultValue so a missing define fails predictably.

Because these are const, they can be evaluated even in const contexts.

const String apiUrl = String.fromEnvironment(
  'API_URL',
  defaultValue: 'http://localhost:8080',
);

const String envName = String.fromEnvironment(
  'ENV',
  defaultValue: 'dev',
);

const bool analyticsEnabled = bool.fromEnvironment(
  'ANALYTICS',
  defaultValue: false,
);

void main() {
  print('env=$envName url=$apiUrl analytics=$analyticsEnabled');
}

Building an AppConfig Object

Scatter String.fromEnvironment calls across your codebase and you lose control. Centralize them in one immutable AppConfig that you resolve once and pass down.

This keeps every flavor difference in one auditable place and makes testing trivial: you just construct an AppConfig with the values you want.

class AppConfig {
  final String envName;
  final String apiUrl;
  final bool analyticsEnabled;

  const AppConfig({
    required this.envName,
    required this.apiUrl,
    required this.analyticsEnabled,
  });

  factory AppConfig.fromEnvironment() {
    return const AppConfig(
      envName: String.fromEnvironment('ENV', defaultValue: 'dev'),
      apiUrl: String.fromEnvironment('API_URL',
          defaultValue: 'http://localhost:8080'),
      analyticsEnabled:
          bool.fromEnvironment('ANALYTICS', defaultValue: false),
    );
  }

  bool get isProd => envName == 'prod';
}

void main() {
  final config = AppConfig.fromEnvironment();
  print('Running in ${config.envName} -> ${config.apiUrl}');
}

Passing Dart-Define on the Command Line

You inject configuration when you run or build. Each --dart-define sets one key. Pair it with the native flavor via --flavor.

  • --flavor staging selects the native variant (id, icon, name).
  • --dart-define feeds your AppConfig.

Typing these every time is error-prone, so teams capture them in scripts or files (next scene).

flutter run \
  --flavor staging \
  --target lib/main.dart \
  --dart-define=ENV=staging \
  --dart-define=API_URL=https://staging.api.acme.com \
  --dart-define=ANALYTICS=true

flutter build apk \
  --release \
  --flavor prod \
  --dart-define=ENV=prod \
  --dart-define=API_URL=https://api.acme.com \
  --dart-define=ANALYTICS=true

Dart-Define-From-File for Cleaner CI

Long --dart-define chains are brittle. Flutter supports --dart-define-from-file, which reads a JSON (or .env-style) file of key/value pairs.

  • Keep one file per environment: config/dev.json, config/staging.json, config/prod.json.
  • Commit non-secret files; inject secret ones in CI from a secure store.

Example config/prod.json and its invocation are shown. The keys map one-to-one to your fromEnvironment lookups.

// config/prod.json
{
  "ENV": "prod",
  "API_URL": "https://api.acme.com",
  "ANALYTICS": true
}

// Invocation:
// flutter build appbundle --release \
//   --flavor prod \
//   --dart-define-from-file=config/prod.json

Android: productFlavors

On Android, declare flavors in android/app/build.gradle. Each flavor overrides the application id suffix and name so builds install side-by-side.

  • applicationIdSuffix appends to the base id (e.g. com.acme.app.dev).
  • resValue overrides the launcher label per flavor.

A flavorDimensions entry is required before listing flavors.

android {
    flavorDimensions "env"
    productFlavors {
        dev {
            dimension "env"
            applicationIdSuffix ".dev"
            resValue "string", "app_name", "Acme Dev"
        }
        staging {
            dimension "env"
            applicationIdSuffix ".staging"
            resValue "string", "app_name", "Acme Staging"
        }
        prod {
            dimension "env"
            resValue "string", "app_name", "Acme"
        }
    }
}

iOS: Schemes and xcconfig

On iOS, flavors map to Xcode schemes backed by build configurations and .xcconfig files. Each scheme sets a distinct PRODUCT_BUNDLE_IDENTIFIER and display name.

  • Create configs like Debug-dev, Release-prod, etc.
  • An .xcconfig per environment overrides the bundle id and DISPLAY_NAME, read in Info.plist via $(DISPLAY_NAME).

Flutter matches --flavor prod to the Xcode scheme named prod.

// ios/Flutter/staging.xcconfig
#include "Generated.xcconfig"
PRODUCT_BUNDLE_IDENTIFIER = com.acme.app.staging
DISPLAY_NAME = Acme Staging

// In Info.plist:
// <key>CFBundleDisplayName</key>
// <string>$(DISPLAY_NAME)</string>

Per-Environment Assets

Flavors often need different assets: a colored DEV banner, a staging app icon, a different Firebase config.

  • Organize assets in folders like assets/dev/, assets/prod/ and select the path at runtime from your AppConfig.
  • For native icons, Android resolves src/dev/res automatically; iOS uses per-config asset catalogs.
  • Place flavor-specific google-services.json under android/app/src/<flavor>/.

The Dart side simply derives the asset path from the active environment.

class AssetPaths {
  final String envName;
  const AssetPaths(this.envName);

  String get logo => 'assets/$envName/logo.png';
  String get configBanner =>
      envName == 'prod' ? '' : 'assets/$envName/banner.png';
}

void main() {
  for (final env in ['dev', 'staging', 'prod']) {
    final paths = AssetPaths(env);
    print('$env logo: ${paths.logo}');
  }
}

Wiring AppConfig into main()

Resolve the config once at startup and make it available to the widget tree (via an InheritedWidget, provider, or a service locator). Avoid reading fromEnvironment deep in your widgets.

  • Build the config before runApp.
  • Show a visible environment banner for non-prod builds to prevent QA confusion.

The snippet below is Flutter framework code, so it is not standalone-runnable, but it shows the canonical entry point.

import 'package:flutter/material.dart';

void main() {
  final config = AppConfig.fromEnvironment();
  runApp(MyApp(config: config));
}

class MyApp extends StatelessWidget {
  final AppConfig config;
  const MyApp({super.key, required this.config});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Acme (${config.envName})',
      debugShowCheckedModeBanner: !config.isProd,
      home: const Scaffold(body: Center(child: Text('Home'))),
    );
  }
}

Quick Check: Where Config Lives

You configured dev, staging, and prod flavors. Test your understanding of how Dart-define values behave.

Recap

You built a complete flavor + environment configuration strategy:

  • Two layers: native flavors (Android productFlavors, iOS schemes/xcconfig) set app identity; dart-define sets runtime config.
  • Type safety: a single Environment enum and an immutable AppConfig resolved once via AppConfig.fromEnvironment().
  • Injection: pass --flavor with --dart-define, or scale cleanly with --dart-define-from-file=config/<env>.json.
  • Assets: per-environment folders and native resource overrides for icons, banners, and Firebase configs.
  • Key insight: dart-define is compile-time and baked into the binary, so changing config always means a rebuild.

The payoff: dev, staging, and prod install side-by-side, fully isolated, and impossible to confuse.

Frequently asked questions

Is the “Build Flavors and Environment Configuration” lesson free?

Yes — the full text of “Build Flavors and Environment Configuration” is free to read here on the web, and the Flutter Mobile Development course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Flutter Mobile Development course, upgrade to CoddyKit PRO.

What will I learn in “Build Flavors and Environment Configuration”?

Define dev, staging, and prod flavors with per-environment assets and Dart-define configs. You practise Flutter Mobile Development with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Flutter Mobile Development?

No prior experience is required. Flutter Mobile Development on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Build Flavors and Environment Configuration” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Flutter Mobile Development lesson?

Yes. Every Flutter Mobile Development lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Build Flavors and Environment Configuration
  2. Automated Pipelines with Fastlane and GitHub Actions
  3. Crash Reporting and Symbolicated Stack Traces
  4. Remote Config, Feature Flags, and Staged Rollouts
← Back to Flutter Mobile Development