Setting up build configurations (Debug, Release, Staging)

Build Configuration Setup (Debug, Release, Staging)

Classic situation: production app ships with hardcoded https://api-dev.myapp.com in base URL. Or testers get build that logs everything to console and crashes from enabled StrictMode. Proper build configuration—each environment has own constants, behavior, settings, not scattered #if DEBUG across code.

iOS: Xcconfig + Build Configurations

Xcode by default has two build configurations: Debug and Release. Add Staging manually: Product → Scheme → Edit Scheme → Duplicate Release → rename to Staging.

Store configuration values in .xcconfig files:

// Config/Debug.xcconfig
API_BASE_URL = https://api-dev.myapp.com
LOG_LEVEL = verbose
BUNDLE_ID_SUFFIX = .debug

// Config/Staging.xcconfig
API_BASE_URL = https://api-staging.myapp.com
LOG_LEVEL = info
BUNDLE_ID_SUFFIX = .staging

// Config/Release.xcconfig
API_BASE_URL = https://api.myapp.com
LOG_LEVEL = error
BUNDLE_ID_SUFFIX =

In Info.plist values pulled via $(API_BASE_URL). In code read via Bundle.main.infoDictionary:

enum AppConfig {
    static var apiBaseURL: URL {
        guard let urlString = Bundle.main.object(forInfoDictionaryKey: "API_BASE_URL") as? String,
              let url = URL(string: urlString) else {
            fatalError("API_BASE_URL not configured")
        }
        return url
    }
}

No #if DEBUG for URLs—only Bundle.

Android: Build Types + Product Flavors

Android configurations managed via build.gradle.kts. Build Types (debug, release, staging) + Product Flavors (free, paid, enterprise) give variant matrix.

android {
    buildTypes {
        debug {
            applicationIdSuffix = ".debug"
            versionNameSuffix = "-debug"
            isDebuggable = true
            buildConfigField("String", "API_BASE_URL", "\"https://api-dev.myapp.com\"")
            buildConfigField("Boolean", "ENABLE_LOGGING", "true")
        }
        create("staging") {
            initWith(getByName("release"))
            applicationIdSuffix = ".staging"
            versionNameSuffix = "-staging"
            buildConfigField("String", "API_BASE_URL", "\"https://api-staging.myapp.com\"")
            buildConfigField("Boolean", "ENABLE_LOGGING", "true")
            signingConfig = signingConfigs.getByName("debug")
        }
        release {
            isMinifyEnabled = true
            buildConfigField("String", "API_BASE_URL", "\"https://api.myapp.com\"")
            buildConfigField("Boolean", "ENABLE_LOGGING", "false")
            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
        }
    }
}

BuildConfig.API_BASE_URL accessible in code after build—generated class, not hardcoded string.

Icons and App Names per Configuration

Staging and Debug builds should visually differ from production. On iOS done via different AppIcon asset in Assets.xcassets + xcconfig condition (ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon-Staging). On Android—via src/debug/res/ and src/staging/res/ with separate ic_launcher and strings.xml (with different app_name).

React Native and Flutter

In React Native, environment configurations managed via react-native-config (.env.staging, .env.production) or via native build types/schemes above. Package react-native-config compiles variables into native code—values not accessible via process.env at JS runtime, safer.

In Flutter—--dart-define or --dart-define-from-file:

flutter build apk --dart-define=API_URL=https://api-staging.myapp.com --flavor staging

Workflow

Audit current configuration management approach → create xcconfig/buildTypes structure → migrate hardcoded values to configs → update CI for building needed variant → setup icons and names → document for team.

Timeline: 1–3 days. Cost calculated individually.