Hi Swift Community!
Today, we’re pleased to announce the initial release of Swift Configuration: a new library that provides a unified approach to reading configuration in your Swift applications.
Configuration management has long been a challenge across different sources and environments. Previously, configuration in Swift had to be manually stitched together from environment variables, command-line arguments, JSON files, and external systems. Swift Configuration creates a common interface for configuration, enabling you to:
-
Read configuration the same way across your codebase using a single configuration reader API that’s usable from both applications and libraries.
-
Quickly get started with a few lines of code using built-in providers for environment variables, command-line arguments, JSON and YAML files, and in-memory values.
-
Build and share custom configuration providers using a public
ConfigProviderprotocol that anyone can implement and share.
Swift Configuration excels in the Swift server ecosystem, where configuration is often read from multiple systems and tools. The library is equally useful in command-line tools, GUI applications, and libraries wherever flexible configuration management is needed.
Getting started
Swift Configuration's key strength lies in its ability to combine multiple configuration providers into a coherent hierarchy. This allows you to establish sensible defaults while providing clean override mechanisms for different deployment scenarios.
For example, if you have default configuration in JSON:
{
"http": {
"timeout": 30
}
}
And want to be able to provide an override using an environment variable:
# Environment variables:
HTTP_TIMEOUT=15
The example below creates the two relevant providers, and uses them to resolve a value for the HTTP timeout:
let config = ConfigReader(providers: [
EnvironmentVariablesProvider(),
try await JSONProvider(filePath: "/etc/config.json")
])
let httpTimeout = config.int(forKey: "http.timeout", default: 60)
print(httpTimeout) // prints 15
The resolver checks providers in the order you specify, so environment variables take precedence over JSON configuration, which in turn overrides your fallback defaults. This eliminates ambiguity about which configuration source is actually being used.
As your configuration needs evolve, enable access logging to track where values are accessed in your code and which providers are responding. This transparency helps maintain confidence even in complex configuration hierarchies.
Advanced capabilities
While the library prioritizes simplicity for basic use cases, it includes powerful features for production environments:
-
Multiple access patterns – synchronous, asynchronous, and reactive watching patterns.
-
Hot reloading – configuration updates without service restarts.
-
Namespacing and scoped readers – organized configuration management through nesting.
-
Access logging – comprehensive debugging and troubleshooting support.
-
Secret redaction – built-in protection for sensitive configuration values.
The complete documentation covers these features in detail.
Community feedback welcome
With version 0.1.0 now available, we're eager to see how the community integrates Swift Configuration into real-world projects. Your experience with different use cases, configuration patterns, and deployment scenarios will help shape the library's evolution.
Please try integrating Swift Configuration into your applications, tools, and libraries, and share your feedback through GitHub issues, pull requests, or Swift Forums discussions.
Stability note
Since this is a pre-1.0 release, libraries that need API stability may want to wait for the 1.0 release, which we expect to ship in the next few months. However, we encourage experimentation and integration testing on development branches – your feedback ensures the 1.0 API meets your requirements.
Links
-
GitHub repo: https://github.com/apple/swift-configuration
-
Documentation: https://swiftpackageindex.com/apple/swift-configuration/documentation
If anyone’s headed to ServerSide.swift next week, check out Honza’s talk on Friday at 16:15 on Swift Configuration – 
