Swift-Configuration

1 hour ago 2

A Swift library for reading configuration in applications and libraries.

📚 Documentation is available on the Swift Package Index.
💻 Examples are available just below, in the Examples directory, and on the Example use cases page.
🚀 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.

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.

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 } }

And want to be able to provide an override for that using an environment variable:

# 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 JSONProvider(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.

Important: While this library's API is still in development, use the .upToNextMinor(from: "...") dependency constraint to avoid unexpected build breakages. Before we reach 1.0, API-breaking changes may occur between minor 0.x versions.

Add the dependency to your Package.swift:

.package(url: "https://github.com/apple/swift-configuration", .upToNextMinor(from: "0.1.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)")

For more, check out the full documentation.

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", .upToNextMinor(from: "0.1.0"), + traits: [.defaults, "OtherFeatureSupport"] )

Available traits:

JSONSupport (default): Adds support for JSONProvider, a ConfigProvider for reading JSON files.
LoggingSupport (opt-in): Adds support for AccessLogger, a way to emit access events into a SwiftLog.Logger.
ReloadingSupport (opt-in): Adds support for auto-reloading variants of file providers, such as ReloadingJSONProvider (when JSONSupport is enabled) and ReloadingYAMLProvider (when YAMLSupport is enabled).
CommandLineArgumentsSupport (opt-in): Adds support for CommandLineArgumentsProvider for parsing command line arguments.
YAMLSupport (opt-in): Adds support for YAMLProvider, a ConfigProvider for reading YAML files.