Working With Xcode Configuration Files

The Good Old #if DEBUG Pattern

We all know this pattern:

And actually, it’s simple and works well. But it does have flaws — it’s not secured because it contains secret data such as passwords and keys right inside your repository. This makes it kind of a mess when you need to distinguish between environments. Additionally, it doesn’t support other types of values such as app name or icon.

Fortunately, we have an elegant solution in the form of a file’s type called XCConfig.

What is XCConfig?

In spite of the blown name, XCConfig (Xcode Configuration File) is just a text file containing key and value pairs. When attaching a configuration file to a build configuration, it can override or modify certain variables in the build and even add new ones. Consequently, this provides flexibility when configuring your app to different environments.

Schemes and Configurations

Before we dive into XCConfig, let’s clarify what schemes and configuration are and how they relate to configuration files.

Schemes are created by default for each target of your project, where the target can be either executable or a framework.

For every scheme, you can define the configuration for running, archives, or testing.

So what is configuration?

The configuration is a set of values that you attach to a scheme and an action. For example, you can define different configurations for different endpoint servers and configure your app in a way that your Production Scheme will archive your project to the production server, but the tests will work with development server (this is just an example of course).

Creating XCConfig Files and Attach Them to Configurations

Before we add configuration files, we need to properly define the configurations for your project. Usually, it is best practice to create a configuration for each stage in your development process. For example -> development, staging, beta, and production.

To create a new configuration, go to your project (not your main target) and in the Info tab, you’ll see the Configurations section. As a default, you have Debug and Release configurations, but you can edit/delete/rename it and create your own configurations.

Now you need to add the XCConfig files. Adding a new configuration file is very easy. Just add a new file, and select Configuration Settings File.

Go back to the Configurations section — now you can attach a configuration file for each configuration you defined, and even for each target.

Note: If you’re using Cocoapods, you’ll have to delete your workspace and your Podfile.lock files, and run Poddfile install again.

Adding Values to Your XCConfig Files

As I mentioned before, using your XCConfig files is very easy. An XCConfig file is just a file with key-value rows.

A few notes about it:

  • Xcode treats “//“ as a comment, even if it’s part of a URL, so take this into account. You can work around this by putting another symbol in place of “//“ and replace it in your code afterward.
  • Each value in the config file is translated to a string afterward, so no need to wrap it with quotation marks.


Sometimes you want to have different files with a default value and inheriting them from a base file (just like classes) can be a solution.

Well, you can do that with #include to other XCConfig files.

For example, you can define a name for your app, and that will be the name in all of your configurations unless otherwise defined.

Accessing Values From Code

But how do we use the values we set in the configuration files? The best way to do that is to set the values in the info.plist. From there the path to the code is very short.

The variable format is $(<Variable name>).

If you want to read it from your code,

Opportunity to Improve Security

Take a look again at your info.plist. Take a look at your code. Did you see any secret keys floating around?

That’s because those values sit in a dedicated file, that you can put in a different, private, and more secure repository.

Using build configuration is not only convenient, but also an opportunity to make your code more secure.


No more manually change environment values, no more #if DEBUG, and no more secret key traveling in your code. XCConfig is a very easy and simple way to solve any configuration issues.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s