Creating and managing multiple app environments in Xcode

After getting on overview on Xcode's build configuration concepts, we can take the next step: adding and managing multiple environments like debug, staging, and release.

Let's walk through the process step by step.

Architecture & Design Patterns for iOS

This book is a practical guide to essential architectural principles and design patterns for iOS development. It covers strategies for building maintainable apps with Swift and SwiftUI, including dependency injection, navigation, common patterns, and modularization.

LEARN MORE

Adding a new build configuration

Xcode already provides Debug and Release configurations by default. To add a custom one (like Staging), we open the project editor, go to the Info tab, and click the + button in the Configurations section.

We can duplicate the Debug configuration and name the new one Staging.

Adding a new configuration.

Creating schemes for each environment

To easily run and test each configuration, we can create separate schemes by opening Manage Schemes from the scheme dropdown and duplicate the default scheme for each environment we want to support (e.g. Staging, Release).

Managing schemes in Xcode.

💡 It's usually best to duplicate the existing scheme. This copies over all relevant settings (like build, test, and archive actions), so we only need to change the build configuration. Creating a scheme from scratch is also possible, but it requires manual setup and is better suited for workflows which are structurally different.

Duplicating a scheme in Xcode.

After duplicating, we rename the schemes accordingly and edit each one to use the matching build configuration for Build, Run, Test, and so on.

Editing a scheme.

Customizing build settings per configuration

Now that our configurations are in place, we can assign different values for each. This is useful for:

• App bundle identifiers
• App icons
• Display names
• Version suffixes

For example, we can adjust the bundle identifier for each configuration by searching for it in the build settings tab:

Customizing build settings for each configuration.

Adding user-defined build settings

For environment-specific variables such as API URLs or feature flags, we can either configure them in build settings or create a wrapper type to check the current environment in code and return custom values based on that. For example:

struct BuildConfiguration {
    enum Environment: String {
        case debug = "Debug"
        case staging = "Staging"
        case release = "Release"
    }

    let environment: Environment

    init() {
        let rawValue = Bundle.main.object(forInfoDictionaryKey: "Environment") as? String ?? "Debug"
        environment = Environment(rawValue: rawValue) ?? .debug
    }
}

Alternatively, we can use Xcode configuration files (xcconfig) to manage large sets of build settings in one central file.

➡️ Continue reading: Working with Xcode configuration files.