English | 日本語

swift-env

Declarative access to environment variable configuration via Swift macros. Wraps Apple swift-configuration to eliminate boilerplate.

Features

• Declarative: just annotate a struct with @Env and its properties with @Value
• Type-safe: supports String, Int, Double, Bool, and RawRepresentable enums
• DI-friendly: init(config: ConfigReader) makes injection straightforward
• Scope support: @Env(scope: "prefix") prepends a key prefix automatically
• Zero runtime overhead: all code is generated at compile time

Quick Start

import Env

@Env
struct GCPConfig {
    @Value("gcp.project.id", default: "my-project")
    var projectId: String

    @Value("firebase.emulator", default: false)
    var useEmulator: Bool
}

// Usage
let config = ConfigReader(provider: EnvironmentVariablesProvider())
let gcp = GCPConfig(config: config)
print(gcp.projectId)  // reads GCP_PROJECT_ID, falls back to "my-project"

Installation

Swift Package Manager

Add to Package.swift:

dependencies: [
    .package(url: "https://github.com/no-problem-dev/swift-env.git", from: "1.0.0")
]

Add to your target:

.target(
    name: "YourTarget",
    dependencies: [
        .product(name: "Env", package: "swift-env")
    ]
)

Macros

@Env

Apply to a struct to auto-generate:

• Keys enum — ConfigKey-typed static properties
• Defaults enum — default value static properties
• init(config: ConfigReader) initializer
• EnvConfigurable conformance (which includes Sendable)

@Env
struct ServerConfig {
    @Value("server.port", default: 8080)
    var port: Int
}

// Expands to:
struct ServerConfig {
    var port: Int

    private enum Keys {
        static let port: ConfigKey = "server.port"
    }

    private enum Defaults {
        static let port = 8080
    }

    public init(config: ConfigReader) {
        self.port = config.int(forKey: Keys.port, default: Defaults.port)
    }
}

extension ServerConfig: EnvConfigurable {}

@Env(scope:)

Providing a scope causes the initializer to call config.scoped(to:) internally:

@Env(scope: "emulator")
struct EmulatorConfig {
    @Value("firestore.host", default: "localhost")
    var firestoreHost: String

    @Value("firestore.port", default: 8090)
    var firestorePort: Int
}

// Pass the root config — scoping is handled internally
let emulator = EmulatorConfig(config: config)
// Reads EMULATOR_FIRESTORE_HOST, EMULATOR_FIRESTORE_PORT

@Value

Apply to a stored property inside an @Env struct to declare its environment key and default:

@Value("key.name", default: defaultValue)
var propertyName: Type

Supported types:

• String — config.string(forKey:default:)
• Int — config.int(forKey:default:)
• Double — config.double(forKey:default:)
• Bool — config.bool(forKey:default:)
• RawRepresentable where RawValue == String — stored as the raw string, restored via Type(rawValue:) ?? default

@EnvGroup

Groups multiple @Env structs and auto-generates init(config:) plus static func load():

@EnvGroup
public struct AppConfig {
    let gcp: GCPConfig
    let server: ServerConfig
}

// Usage
let app = AppConfig.load()
print(app.gcp.projectId)

Environment Variable Mapping

Keys follow swift-configuration naming rules — dot-separated segments become UPPER_SNAKE_CASE:

With a scope, the scope name is prepended:

Advanced Usage

Combining Multiple Configs

@Env
struct GCPConfig {
    @Value("gcp.project.id", default: "stockle-app")
    var projectId: String

    @Value("firebase.emulator", default: false)
    var useEmulator: Bool
}

@Env(scope: "emulator")
struct EmulatorConfig {
    @Value("firestore.host", default: "localhost")
    var firestoreHost: String

    @Value("firestore.port", default: 8090)
    var firestorePort: Int
}

@EnvGroup
public struct AppConfig {
    let gcp: GCPConfig
    let emulator: EmulatorConfig
}

// Dependency injection
let app = AppConfig.load()
let gcp = app.gcp
let emulator = app.emulator

Dependencies

Documentation

Full API documentation is available on GitHub Pages.

License

MIT License — see LICENSE for details.