koanf

koanf is a configuration management library for Go applications, built as a cleaner, lighter alternative to spf13/viper. It defines two small interfaces — Provider (where config comes from: a file, environment variables, S3, Vault, etcd, command-line flags) and Parser (how raw bytes become a nested map: JSON, YAML, TOML, HCL, HJSON, dotenv, and more) — and lets an application compose them freely, loading and merging multiple sources into a single typed configuration store.

Every provider and parser beyond the core lives in its own Go module under providers/ and parsers/, so consuming code only pulls in the dependencies it actually uses instead of the large dependency graph that comes bundled with heavier alternatives. koanf preserves key casing exactly as written in source files, exposes delimited key-path access (e.g. app.server.port) with a configurable delimiter, and supports struct unmarshalling, custom merge functions, and file-watching for live config reloads.

What You Get

• A core Koanf struct with Load(), Get(), typed getters (String, Int, Bool, Duration, slices/maps of each), and Unmarshal() into structs via a koanf struct tag
• Composable Provider and Parser interfaces so any config source or format can be plugged in, including custom, application-specific ones
• Official providers for files, env vars, POSIX/basic CLI flags, S3, Vault, Consul, etcd, AWS AppConfig/Parameter Store, Azure Key Vault, Kubernetes mounts, and raw bytes/structs/maps
• Official parsers for JSON, YAML, TOML, HCL, HJSON, dotenv, KDL, NestedText, and HUML, each importable independently to keep binaries lean
• Deterministic, order-dependent merging across multiple loaded sources, with an optional custom merge function via WithMergeFunc
• File-watching support (Watch/Unwatch) on select providers for live config reloads without restarting the process

Common Use Cases

• Layered application config - load a base JSON or YAML file, then override specific keys with environment variables or CLI flags for different deployment environments
• Twelve-factor services - read most settings from env vars in containerized deployments while keeping local file-based defaults for development
• Secrets-aware configuration - merge non-sensitive file config with secrets pulled at runtime from Vault, AWS Parameter Store, or Azure Key Vault
• Dynamic config reloading - watch a mounted Kubernetes ConfigMap or local file and reload settings into a running service without a restart
• Struct-typed app settings - unmarshal merged configuration directly into typed Go structs with the koanf tag instead of manually reading individual keys

Under The Hood

Architecture The library centers on a single Koanf struct (koanf.go) holding a flattened and a nested map[string]any, guarded by a sync.RWMutex for concurrent-safe reads. Load() accepts any Provider (interfaces.go) that returns either raw bytes (parsed via a supplied Parser) or an already-parsed map, then merges the result into the existing store using either a default merge or a caller-supplied function passed through the Option/WithMergeFunc mechanism in options.go. Every concrete provider (file, env, S3, Vault, Consul, etcd, AppConfig, Azure Key Vault, Kubernetes mount, POSIX/basic flags, raw bytes, structs, confmap) and every parser (JSON, YAML, TOML, HCL, HJSON, dotenv, KDL, NestedText, HUML) is implemented against these two interfaces in its own subdirectory, so the core package stays free of format- and source-specific logic; a go.work workspace ties the ~25 modules together for local development while each ships as an independently versioned Go module for consumers.

Tech Stack Written in Go (module targets Go 1.23+), with the core depending on only three small external packages: go-viper/mapstructure/v2 for struct unmarshalling, knadh/koanf/maps (the project’s own map-flattening helper module) for key-path flattening, and mitchellh/copystructure for safe deep copies during merges. Provider and parser submodules add their own scoped dependencies only when installed (e.g. AWS SDK for S3/Parameter Store, Vault’s API client, go-yaml/go-toml/HCL parser libraries), keeping the dependency footprint proportional to what an application actually uses rather than pulling in everything up front.

Code Quality The project ships an extensive test suite (tests/koanf_test.go alone runs over 2,100 lines) covering flat and nested key merging, delimiter handling, struct unmarshalling, provider/parser combinations, and concurrent access, using testify’s assert/require alongside standard library testing; a GitHub Actions workflow (test.yml) runs tests on every push. Error handling is explicit and idiomatic Go — functions return wrapped errors via fmt.Errorf rather than panicking, with Must*-prefixed getter variants offered separately for callers who want panic-on-missing-value semantics. Exported identifiers carry doc comments throughout, and naming is consistent with Go conventions across the whole provider/parser surface.

What Makes It Unique koanf’s core differentiator is architectural: rather than hardcoding sources and formats into a monolithic core (the approach it explicitly critiques in spf13/viper — forced key lowercasing, coupled parsing/file-extension logic, dependency bloat), it isolates every provider and parser behind two minimal interfaces and its own Go module, so an application’s binary and dependency tree only grow with the sources and formats it actually opts into. It also preserves key casing exactly as declared in source configuration, avoiding a class of subtle bugs common in config libraries that silently normalize keys.