Swift Configuration

• 📚 Documentation is available on the Swift Package Index.
• 💻 Examples are available just below, in the Examples directory, and on the Example use cases page.
• 📺 Video introduction is available on YouTube.
• 🚀 Contributions are welcome, please see CONTRIBUTING.md.
• 🪪 License is Apache 2.0, repeated in LICENSE.
• 🔒 Security issues should be reported via the process in SECURITY.md.

Overview

Swift Configuration defines an abstraction layer between configuration readers and providers.

Applications and libraries _read_ configuration through a consistent API, while the actual _provider_ is set up once at the application's entry point.

Examples

Swift Configuration allows you to combine multiple providers in a hierarchy, where values from higher-priority sources override those from lower-priority ones.

For example, if you have a default configuration in JSON:

{
  "http": {
    "timeout": 30
  }
}

# Environment variables:
HTTP_TIMEOUT=15

The example code below creates the two relevant providers, and resolves them in the order you list:

let config = ConfigReader(providers: [
    EnvironmentVariablesProvider(),
    try await FileProvider<JSONSnapshot>(filePath: "/etc/config.json")
])
let httpTimeout = config.int(forKey: "http.timeout", default: 60)
print(httpTimeout) // prints 15

The resolved configuration value is 15 from the environment variable. Without the environment variable, it would use 30 from the JSON file. If both sources are unavailable, the fallback default of 60 is returned.

Tip: More example use cases are described in example use cases, and complete working examples are available in the Examples directory.

Quick start

Add the dependency to your Package.swift:

.package(url: "https://github.com/apple/swift-configuration", from: "1.0.0")

Add the library dependency to your target:

.product(name: "Configuration", package: "swift-configuration")

Import and use in your code:

import Configuration
let config = ConfigReader(provider: EnvironmentVariablesProvider())
let httpTimeout = config.int(forKey: "http.timeout", default: 60)
print("The HTTP timeout is: \(httpTimeout)")

Getting started guides

• Configuring applications
• Configuring libraries
• Migrating to Swift Configuration

Package traits

This package offers additional integrations you can enable using package traits. To enable an additional trait on the package, update the package dependency:

.package(
    url: "https://github.com/apple/swift-configuration",
    from: "1.0.0",
+   traits: [.defaults, "YAML"]
)

Available traits:

• JSON (default): Adds support for FileProvider, a ConfigProvider for reading JSON files.
• Logging (opt-in): Adds support for AccessLogger, a way to emit access events into a SwiftLog.Logger.
• Reloading (opt-in): Adds support for auto-reloading variants of file providers, such as ReloadingFileProvider (when JSON is enabled), ReloadingFileProvider (when YAML is enabled), and ReloadingFileProvider (when PropertyList is enabled).
• CommandLineArguments (opt-in): Adds support for CommandLineArgumentsProvider for parsing command line arguments.
• YAML (opt-in): Adds support for FileProvider, a ConfigProvider for reading YAML files.
• PropertyList (opt-in): Adds support for FileProvider, a ConfigProvider for reading property list files.

Supported platforms and minimum versions

The library is supported on Apple platforms, Linux, Windows, and Android.

• macOS 15+
• iOS 18+
• tvOS 18+
• watchOS 11+
• visionOS 2+
• Linux
• Windows
• Android API 28+

Configuration providers

Built-in providers

The library includes comprehensive built-in provider support:

• Environment variables: EnvironmentVariablesProvider
• Command-line arguments: CommandLineArgumentsProvider
• JSON file: FileProvider and ReloadingFileProvider
• YAML file: FileProvider and ReloadingFileProvider
• Property list file: FileProvider and ReloadingFileProvider
• Directory of files: DirectoryFilesProvider
• In-memory: InMemoryProvider and MutableInMemoryProvider
• Key transforming: KeyMappingProvider

Community providers

• TOML file: mattt/swift-configuration-toml
• AWS Secrets Manager: songshift/swift-configuration-aws

Key features

• 3 access patterns: synchronous, asynchronous, and watching
• Provider hierarchy
• Hot reloading/watching value updates
• Namespacing and scoped readers
• Debugging and troubleshooting
• Redaction of secrets
• Consistent snapshots
• Custom key syntax

Documentation

Comprehensive documentation is hosted on the Swift Package Index.