Building Multi-Flavor Apps for White-Label Solutions in Flutter

Introduction

White-label mobile development requires shipping multiple app variants with unique branding, assets, and configurations from a single codebase. Flutter’s flavor support lets teams manage multiple app configurations—often called flavors—through build-time flags. In this tutorial, you’ll learn how to set up flavors, organize assets and code per client, automate builds with CI/CD, and ensure robust testing. By the end, you’ll have a maintainable multi-flavor Flutter project ready for white-label distribution.

Configuring Flavors in Flutter

Flutter flavors rely on passing Dart defines and using custom entry points. Start by creating separate main_<flavor>.dart files under lib/:

// lib/main_clientA.dart
import 'package:flutter/material.dart';
import 'app.dart';

void main() {
  runApp(MyApp(ThemeData(primaryColor: Colors.blue)));
}

Add build configurations in android/app/build.gradle:

productFlavors {
    clientA { applicationId "com.example.clientA" }
    clientB { applicationId "com.example.clientB" }
}

Invoke builds with: flutter run --flavor clientA -t lib/main_clientA.dart. On iOS, duplicate the Runner target in Xcode and set the FLAVOR scheme.

Structuring White-Label Assets

Organizing assets per flavor avoids accidental leaks and simplifies updates. Create a folder structure:

In pubspec.yaml, reference dynamic asset paths using Dart code rather than static lists. Load flavor at runtime:

class FlavorConfig {
  static String flavor;
  static Future<void> load() async {
    const flavorName = String.fromEnvironment('FLAVOR');
    flavor = flavorName;
  }
}

// Usage
final logoPath = 'assets/${FlavorConfig.flavor}/logo.png';

Call FlavorConfig.load() before runApp() in each main_<flavor>.dart.

Environment-Specific Code and Dependencies

Sometimes flavors need distinct behavior: feature toggles, API endpoints, or packages. Use compile-time variables and conditional imports:

// api.dart
import 'api_stub.dart'
    if (dart.library.io) 'api_mobile.dart';

// build with
dart define: FLAVOR=clientA

For REST endpoints:

class ApiConfig {
  static const endpoint = String.fromEnvironment(
    'API_ENDPOINT',
    defaultValue: 'https://api.default.com',
  );
}

Set --dart-define=API_ENDPOINT=https://api.clientA.com when building. This approach integrates seamlessly with Flutter’s tree shaking.

Automating Builds with CI/CD

Manual flavor builds become error-prone as you add clients. Use CI pipelines (GitHub Actions, GitLab CI) to automate:

jobs:
  build_flavor:
    strategy:
      matrix:
        flavor: [clientA, clientB]
    steps:
      - uses: actions/checkout@v2
      - name: Set up Flutter
        uses: subosito/flutter-action@v2
      - name: Build APK
        run: flutter build apk --flavor ${{ matrix.flavor }} -t lib/main_${{ matrix.flavor }}.dart
      - name: Upload
        uses: actions/upload-artifact@v2
        with:
          name: apk_${{ matrix.flavor }}
          path

This pipeline loops through each flavor, builds an artifact, and stores it for distribution. Extend similar jobs for iOS builds.

Testing and Deployment

Flavor-aware testing ensures each variant behaves correctly. Use integration tests with flavor flags:

flutter:
  integration_test:
    suite

Run tests per flavor:

flutter test integration_test/all_tests.dart --flavor clientA -t

For deployment, configure your Play Store and App Store pipelines to pick up flavor artifacts. Ensure release notes and store listings align with each client’s branding.

Vibe Studio

Vibe Studio, powered by Steve’s advanced AI agents, is a revolutionary no-code, conversational platform that empowers users to quickly and efficiently create full-stack Flutter applications integrated seamlessly with Firebase backend services. Ideal for solo founders, startups, and agile engineering teams, Vibe Studio allows users to visually manage and deploy Flutter apps, greatly accelerating the development process. The intuitive conversational interface simplifies complex development tasks, making app creation accessible even for non-coders.

Conclusion

Building multi-flavor apps in Flutter streamlines white-label solutions by centralizing code and configurations. With flavor-specific entry points, asset organization, environment flags, and CI/CD automation, you can maintain dozens of branded apps without code duplication. Rigorous testing per flavor safeguards quality. Apply these patterns to scale your Flutter white-label offerings efficiently.